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

focus_data_toolkit/validate/bundle.py

@@ -0,0 +1,254 @@
+"""Validate a *bundle* of FOCUS datasets together (P1.4).
+
+This layer is deliberately separate from the per-dataset linter (``model/validator.py``): it
+asserts the cross-dataset guarantees the linter explicitly does not — referential integrity,
+uniqueness, currency/period/issuer coherence, reconciliation, split cost allocation, and
+commitment lifecycle. ``validate_dataset_bundle`` returns a :class:`BundleReport` whose
+diagnostics are grouped by severity (error / warning / info / not-executable / not-applicable)
+and which serialises to JSON.
+
+Memory model: no dataset is ever materialised. Each check consumes its inputs in independent
+forward passes, so every bundle value must be **re-iterable** — a list, or an object whose
+``__iter__`` opens a fresh scan (e.g. a staged-file reader); a one-shot generator is rejected.
+Per-key lookup state (seen ids, foreign-key targets, running sums) is created through
+``index_factory``, which a streaming caller points at a disk-spilling map
+(:class:`~focus_data_toolkit.storage.spill.SpillableIndexPool`) to validate bundles far
+larger than RAM.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, MutableMapping
+from dataclasses import dataclass
+from decimal import Decimal
+
+from focus_data_toolkit.errors import Diagnostic, Severity
+from focus_data_toolkit.validate import allocation, corrections, reconciliation, referential
+
+Rows = Iterable[Mapping[str, str]]
+Bundle = Mapping[str, Rows]
+IndexFactory = Callable[[], MutableMapping[str, str]]
+
+
+@dataclass
+class BundleReport:
+    """Result of validating a dataset bundle."""
+
+    diagnostics: list[Diagnostic]
+    checks_run: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        """No failing (ERROR) diagnostics."""
+        return not any(d.is_failure for d in self.diagnostics)
+
+    def by_severity(self, severity: Severity) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity is severity]
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        return self.by_severity(Severity.ERROR)
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return self.by_severity(Severity.WARNING)
+
+    def counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {s.value: 0 for s in Severity}
+        for diag in self.diagnostics:
+            counts[diag.severity.value] += 1
+        return counts
+
+    def as_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "counts": self.counts(),
+            "checks_run": list(self.checks_run),
+            "diagnostics": [d.as_dict() for d in self.diagnostics],
+        }
+
+    def format(self) -> str:
+        counts = self.counts()
+        header = "bundle validation: " + ("OK" if self.ok else "FAILED")
+        summary = ", ".join(f"{k.lower()}={v}" for k, v in counts.items() if v)
+        blocks = [header + (f" ({summary})" if summary else "")]
+        blocks.extend(d.format() for d in self.diagnostics)
+        return "\n".join(blocks)
+
+
+def _note(code: str, severity: Severity, message: str, datasets: tuple[str, ...]) -> Diagnostic:
+    return Diagnostic(code=code, severity=severity, message=message, datasets=datasets)
+
+
+def _reiterable(name: str, rows: Rows) -> Rows:
+    """Reject one-shot iterators: every check opens its own fresh pass over the rows."""
+    if iter(rows) is rows:
+        raise TypeError(
+            f"bundle dataset {name!r} is a one-shot iterator; validate_dataset_bundle "
+            "requires re-iterable rows (a list, or an object whose __iter__ opens a fresh scan)"
+        )
+    return rows
+
+
+def _has_rows(rows: Rows) -> bool:
+    for _ in rows:
+        return True
+    return False
+
+
+def validate_dataset_bundle(
+    bundle: Bundle,
+    *,
+    invoice_detail_authoritative: bool = False,
+    rounding_tolerance: Decimal | None = None,
+    index_factory: IndexFactory | None = None,
+) -> BundleReport:
+    """Validate the datasets in ``bundle`` against each other.
+
+    ``bundle`` maps FOCUS dataset names to their rows — each value must be re-iterable (see
+    the module docstring); nothing is materialised. ``invoice_detail_authoritative`` gates
+    the Cost-and-Usage <-> Invoice-Detail sum reconciliation: it runs only when the Invoice
+    Detail comes from a real invoice (a toolkit-derived Invoice Detail reconciles by
+    construction, so reconciling it would be circular). ``rounding_tolerance`` overrides the
+    reconciliation tolerance. ``index_factory`` supplies the per-key lookup state (``dict``
+    when omitted; pass ``SpillableIndexPool(...).make_map`` for bounded memory).
+    """
+    factory: IndexFactory = index_factory if index_factory is not None else dict
+    cu = _reiterable("Cost and Usage", bundle.get("Cost and Usage", ()))
+    invd = _reiterable("Invoice Detail", bundle.get("Invoice Detail", ()))
+    bp = _reiterable("Billing Period", bundle.get("Billing Period", ()))
+    cc = _reiterable("Contract Commitment", bundle.get("Contract Commitment", ()))
+    has_cu, has_invd, has_bp, has_cc = (_has_rows(r) for r in (cu, invd, bp, cc))
+
+    diagnostics: list[Diagnostic] = []
+    checks: list[str] = []
+
+    def run(name: str, produced: list[Diagnostic]) -> None:
+        checks.append(name)
+        diagnostics.extend(produced)
+
+    def _refs_present(rows: Rows, column: str) -> bool:
+        return any((r.get(column) or "").strip() for r in rows)
+
+    # Referential integrity.
+    if has_invd:
+        run(
+            "unique_invoice_detail_ids",
+            referential.check_unique_invoice_detail_ids(invd, index_factory=factory),
+        )
+    if has_cc:
+        run(
+            "unique_contract_commitment_ids",
+            referential.check_unique_contract_commitment_ids(cc, index_factory=factory),
+        )
+    if has_cu and has_invd:
+        run(
+            "cost_and_usage_invoice_detail_fk",
+            referential.check_cost_and_usage_invoice_detail_fk(
+                cu, invd, index_factory=factory
+            ),
+        )
+        run(
+            "cost_and_usage_invoice_detail_consistency",
+            referential.check_cost_and_usage_invoice_detail_consistency(
+                cu, invd, index_factory=factory
+            ),
+        )
+    elif has_cu and _refs_present(cu, "InvoiceDetailId"):
+        # References exist but their target table is absent -> the FK check cannot resolve them.
+        diagnostics.append(
+            _note(
+                "FDT-BUNDLE-001",
+                Severity.NOT_EXECUTABLE,
+                "Cost and Usage InvoiceDetailId references cannot be checked: the Invoice Detail "
+                "dataset is absent from the bundle",
+                ("Cost and Usage", "Invoice Detail"),
+            )
+        )
+    if has_cu and has_cc:
+        run(
+            "contract_applied_fk",
+            referential.check_contract_applied_fk(cu, cc, index_factory=factory),
+        )
+    elif has_cu and _refs_present(cu, "ContractApplied"):
+        diagnostics.append(
+            _note(
+                "FDT-BUNDLE-001",
+                Severity.NOT_EXECUTABLE,
+                "Cost and Usage ContractApplied references cannot be checked: the Contract "
+                "Commitment dataset is absent from the bundle",
+                ("Cost and Usage", "Contract Commitment"),
+            )
+        )
+    if has_cu and has_bp:
+        run(
+            "billing_period_coverage",
+            referential.check_billing_period_coverage(cu, bp, index_factory=factory),
+        )
+
+    # Reconciliation (only for an authoritative Invoice Detail).
+    if has_cu and has_invd:
+        if invoice_detail_authoritative:
+            tolerance = (
+                rounding_tolerance
+                if rounding_tolerance is not None
+                else reconciliation.DEFAULT_TOLERANCE
+            )
+            run(
+                "reconcile_invoice_detail",
+                reconciliation.reconcile_invoice_detail(
+                    cu, invd, tolerance=tolerance, index_factory=factory
+                ),
+            )
+        else:
+            diagnostics.append(
+                _note(
+                    "FDT-BUNDLE-002",
+                    Severity.NOT_APPLICABLE,
+                    "Cost and Usage <-> Invoice Detail reconciliation skipped: Invoice Detail is "
+                    "not marked authoritative (a toolkit-derived Invoice Detail reconciles by "
+                    "construction)",
+                    ("Cost and Usage", "Invoice Detail"),
+                )
+            )
+    elif invoice_detail_authoritative:
+        diagnostics.append(
+            _note(
+                "FDT-BUNDLE-001",
+                Severity.NOT_EXECUTABLE,
+                "reconciliation not executable: Cost and Usage or Invoice Detail is absent",
+                ("Cost and Usage", "Invoice Detail"),
+            )
+        )
+
+    # Split cost allocation and correction integrity (self-contained within Cost and Usage).
+    if has_cu:
+        run(
+            "split_allocation",
+            allocation.validate_split_allocation(cu, index_factory=factory),
+        )
+        run(
+            "correction_references",
+            corrections.check_correction_references(cu, index_factory=factory),
+        )
+        run(
+            "correction_net_sums",
+            corrections.check_correction_net_sums(cu, index_factory=factory),
+        )
+        run(
+            "no_duplicate_charge_keys",
+            corrections.check_no_duplicate_charge_keys(cu, index_factory=factory),
+        )
+
+    # Commitment lifecycle.
+    if has_cc:
+        run("contract_commitment_periods", corrections.check_contract_commitment_periods(cc))
+        run(
+            "contract_commitment_percentages",
+            corrections.check_contract_commitment_percentages(cc),
+        )
+
+    return BundleReport(diagnostics=diagnostics, checks_run=tuple(checks))
+
+
+__all__ = ["Bundle", "BundleReport", "validate_dataset_bundle"]

focus_data_toolkit/validate/codes.py

@@ -0,0 +1,93 @@
+"""Stable catalogue of focus-data-toolkit diagnostic codes.
+
+Codes are **stable** identifiers — once assigned they are never renumbered or reused — so
+downstream tooling can key on them across releases. Namespaces:
+
+* ``FDT-DET-*``   — schema / version detection
+* ``FDT-CROSS-*`` — inter-dataset referential integrity & reconciliation
+* ``FDT-ALLOC-*`` — split cost allocation
+* ``FDT-CORR-*``  — corrections / credits / billing lifecycle
+* ``FDT-IO-*``    — input / output / format
+
+Each code has a default severity and a one-line summary; call :func:`spec` to look one up.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from focus_data_toolkit.errors import Severity
+
+
+@dataclass(frozen=True)
+class CodeSpec:
+    code: str
+    default_severity: Severity
+    summary: str
+
+
+def _s(code: str, sev: Severity, summary: str) -> tuple[str, CodeSpec]:
+    return code, CodeSpec(code, sev, summary)
+
+
+CATALOG: dict[str, CodeSpec] = dict([
+    # --- detection ---------------------------------------------------------------
+    _s("FDT-DET-001", Severity.ERROR, "schema/version detection confidence too low"),
+    _s("FDT-DET-002", Severity.ERROR, "ambiguous schema (multiple candidate versions/datasets)"),
+    _s("FDT-DET-003", Severity.ERROR, "forced version incompatible with the header"),
+    _s("FDT-DET-004", Severity.WARNING, "unknown non-x_ columns present in the source"),
+    # --- multi-provider / context ------------------------------------------------
+    _s("FDT-CTX-001", Severity.WARNING, "source carries multiple provider contexts"),
+    _s("FDT-CTX-002", Severity.WARNING, "source carries multiple invoice issuers"),
+    _s("FDT-CTX-003", Severity.WARNING, "source carries multiple billing currencies"),
+    _s("FDT-CTX-004", Severity.INFO, "a representative context was chosen for enrichment"),
+    # --- cross-dataset referential integrity & reconciliation --------------------
+    _s("FDT-CROSS-001", Severity.ERROR, "duplicate identifier where uniqueness is required"),
+    _s("FDT-CROSS-002", Severity.ERROR, "identifier collides across datasets"),
+    _s("FDT-CROSS-010", Severity.ERROR, "ContractApplied references an unknown ContractCommitmentId"),
+    _s("FDT-CROSS-011", Severity.ERROR, "referenced Contract Commitment not found"),
+    _s("FDT-CROSS-014", Severity.ERROR, "Cost and Usage InvoiceDetailId not found in Invoice Detail"),
+    _s("FDT-CROSS-015", Severity.ERROR, "linked record differs on an identifying attribute (wrong invoice line)"),
+    _s("FDT-CROSS-020", Severity.ERROR, "currency mismatch between linked records"),
+    _s("FDT-CROSS-021", Severity.ERROR, "billing period mismatch between linked records"),
+    _s("FDT-CROSS-022", Severity.ERROR, "invoice issuer mismatch between linked records"),
+    _s("FDT-CROSS-023", Severity.ERROR, "billing account mismatch between linked records"),
+    _s("FDT-CROSS-030", Severity.ERROR, "sum reconciliation mismatch beyond tolerance"),
+    _s("FDT-CROSS-031", Severity.WARNING, "invoice-detail line has no matching Cost and Usage rows"),
+    _s("FDT-CROSS-040", Severity.ERROR, "no Billing Period for a (period, issuer) seen in Cost and Usage"),
+    _s("FDT-CROSS-041", Severity.ERROR, "a closed billing period was modified"),
+    _s("FDT-CROSS-050", Severity.ERROR, "contract commitment period start is not before its end"),
+    _s("FDT-CROSS-051", Severity.ERROR, "percentage value outside its allowed range"),
+    # --- split cost allocation ---------------------------------------------------
+    _s("FDT-ALLOC-001", Severity.ERROR, "allocation ratios do not sum to 1 within tolerance"),
+    _s("FDT-ALLOC-002", Severity.ERROR, "allocated costs do not sum to the origin charge"),
+    _s("FDT-ALLOC-003", Severity.ERROR, "inconsistent allocation method within a group"),
+    _s("FDT-ALLOC-004", Severity.ERROR, "duplicate allocated resource within a group"),
+    _s("FDT-ALLOC-005", Severity.ERROR, "incomplete allocation group (missing required information)"),
+    _s("FDT-ALLOC-006", Severity.ERROR, "allocation ratio outside [0, 1]"),
+    _s("FDT-ALLOC-007", Severity.ERROR, "inconsistent unit within an allocation group"),
+    # --- corrections / lifecycle -------------------------------------------------
+    _s("FDT-CORR-001", Severity.ERROR, "correction references a missing invoice/charge"),
+    _s("FDT-CORR-002", Severity.ERROR, "net sum of a correction set does not reconcile"),
+    _s("FDT-CORR-003", Severity.ERROR, "correction overwrites an original row (no audit trail)"),
+    _s("FDT-CORR-004", Severity.ERROR, "invoice status transition is not allowed"),
+    # --- bundle coverage (a check could not run / does not apply) ----------------
+    _s("FDT-BUNDLE-001", Severity.NOT_EXECUTABLE, "a cross-dataset check could not run (data absent)"),
+    _s("FDT-BUNDLE-002", Severity.NOT_APPLICABLE, "a cross-dataset check does not apply to this bundle"),
+    # --- io / format -------------------------------------------------------------
+    _s("FDT-IO-001", Severity.ERROR, "malformed input record (wrong field count)"),
+    _s("FDT-IO-002", Severity.ERROR, "decimal value exceeds the target Parquet scale/precision"),
+    _s("FDT-IO-003", Severity.ERROR, "destination already exists"),
+    _s("FDT-IO-004", Severity.WARNING, "high-cardinality Parquet partition key (many small files)"),
+    _s("FDT-IO-005", Severity.ERROR, "insufficient free space on the output filesystem"),
+    _s("FDT-IO-006", Severity.ERROR, "insufficient work-filesystem space or temp budget exceeded"),
+])
+
+
+def spec(code: str) -> CodeSpec:
+    """Return the :class:`CodeSpec` for ``code`` (raises ``KeyError`` if unknown)."""
+    return CATALOG[code]
+
+
+def default_severity(code: str) -> Severity:
+    return CATALOG[code].default_severity

focus_data_toolkit/validate/corrections.py

@@ -0,0 +1,245 @@
+"""Commitment lifecycle and correction-integrity checks.
+
+Phase A covers the cheap, spec-grounded temporal and percentage-range checks on Contract
+Commitment, plus a forward-compatible correction-reference check: a Cost and Usage correction
+line (``ChargeClass="Correction"``) may point at the charge it corrects via the toolkit
+extension ``x_CorrectionOf`` -> an original row's ``x_ChargeKey``; the referenced original must
+still be present (corrections never silently overwrite history). Deeper correction scenarios
+arrive with the Phase B generators.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, MutableMapping, Sequence
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from focus_data_toolkit.errors import Diagnostic, Severity
+
+Rows = Sequence[Mapping[str, str]]
+#: Inputs are consumed in forward passes only, so any (re-)iterable of rows works.
+RowStream = Iterable[Mapping[str, str]]
+#: Factory for per-key lookup state (``dict`` by default; a spillable map for streaming).
+IndexFactory = Callable[[], MutableMapping[str, str]]
+
+_PERCENTAGE_COLUMNS = (
+    "ContractCommitmentDiscountPercentage",
+    "ContractCommitmentPaymentUpfrontPercentage",
+)
+_PERIOD_PAIRS = (
+    ("ContractCommitmentPeriodStart", "ContractCommitmentPeriodEnd"),
+    ("ContractPeriodStart", "ContractPeriodEnd"),
+)
+
+
+def _parse_dt(value: str) -> datetime | None:
+    try:
+        parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    # Require a timezone (FOCUS Date/Time is UTC 'Z'). A naive value is malformed for this
+    # lifecycle check; returning None avoids a naive-vs-aware TypeError on comparison and
+    # lets the per-dataset linter report the bad Date/Time format.
+    return parsed if parsed.tzinfo is not None else None
+
+
+def check_contract_commitment_periods(contract_commitment: RowStream) -> list[Diagnostic]:
+    """Each commitment/contract period must start strictly before it ends."""
+    out: list[Diagnostic] = []
+    for i, row in enumerate(contract_commitment, start=1):
+        for start_col, end_col in _PERIOD_PAIRS:
+            start, end = _parse_dt(row.get(start_col, "")), _parse_dt(row.get(end_col, ""))
+            if start is None or end is None or start < end:
+                continue
+            out.append(
+                Diagnostic(
+                    code="FDT-CROSS-050",
+                    severity=Severity.ERROR,
+                    message=f"{start_col} is not before {end_col}",
+                    datasets=("Contract Commitment",),
+                    dataset="Contract Commitment",
+                    line_number=i,
+                    column=start_col,
+                    expected=f"< {row.get(end_col)}",
+                    actual=row.get(start_col, ""),
+                    record_keys={"ContractCommitmentId": (row.get("ContractCommitmentId") or "")},
+                )
+            )
+    return out
+
+
+def check_contract_commitment_percentages(contract_commitment: RowStream) -> list[Diagnostic]:
+    """Percentage columns must be within [0, 1]."""
+    out: list[Diagnostic] = []
+    for i, row in enumerate(contract_commitment, start=1):
+        for col in _PERCENTAGE_COLUMNS:
+            raw = (row.get(col) or "").strip()
+            if not raw:
+                continue
+            try:
+                value = Decimal(raw)
+            except InvalidOperation:
+                continue  # value-format is the per-dataset linter's job
+            if not value.is_finite():
+                continue  # NaN/Infinity is a format issue for the linter, not a range error
+            if value < 0 or value > 1:
+                out.append(
+                    Diagnostic(
+                        code="FDT-CROSS-051",
+                        severity=Severity.ERROR,
+                        message=f"{col} value {raw} is outside [0, 1]",
+                        datasets=("Contract Commitment",),
+                        dataset="Contract Commitment",
+                        line_number=i,
+                        column=col,
+                        actual=raw,
+                        record_keys={"ContractCommitmentId": (row.get("ContractCommitmentId") or "")},
+                    )
+                )
+    return out
+
+
+def _is_correction(row: Mapping[str, str]) -> bool:
+    return (row.get("ChargeClass") or "").strip().casefold() == "correction"
+
+
+def _dec(value: str | None) -> Decimal | None:
+    try:
+        parsed = Decimal((value or "").strip())
+    except InvalidOperation:
+        return None
+    return parsed if parsed.is_finite() else None
+
+
+def check_no_duplicate_charge_keys(
+    cost_and_usage: RowStream, *, index_factory: IndexFactory = dict
+) -> list[Diagnostic]:
+    """``x_ChargeKey`` must be unique: reusing one silently overwrites an auditable line.
+
+    Corrections are appended as *new* keyed rows (``x_ChargeKey`` + ``x_CorrectionOf``), so a
+    repeated key means an original (or a prior correction) was overwritten rather than amended.
+    """
+    seen = index_factory()
+    out: list[Diagnostic] = []
+    for i, row in enumerate(cost_and_usage, start=1):
+        key = (row.get("x_ChargeKey") or "").strip()
+        if not key:
+            continue
+        if key in seen:
+            out.append(
+                Diagnostic(
+                    code="FDT-CORR-003",
+                    severity=Severity.ERROR,
+                    message=f"x_ChargeKey {key!r} appears on rows {seen[key]} and {i} — a "
+                    "correction must add a new keyed row, never overwrite an original",
+                    datasets=("Cost and Usage",),
+                    dataset="Cost and Usage",
+                    line_number=i,
+                    column="x_ChargeKey",
+                    value=key,
+                    record_keys={"x_ChargeKey": key},
+                )
+            )
+        else:
+            seen[key] = str(i)
+    return out
+
+
+def check_correction_net_sums(
+    cost_and_usage: RowStream,
+    *,
+    tolerance: Decimal = Decimal("0.01"),
+    index_factory: IndexFactory = dict,
+) -> list[Diagnostic]:
+    """The net of a correction set must equal the declared ``x_NetCharge``.
+
+    A correction set is an original charge (``x_ChargeKey`` == the corrections'
+    ``x_CorrectionOf``) plus every correction pointing at it. When a correction declares the
+    post-correction net in ``x_NetCharge``, the arithmetic sum of ``BilledCost`` over the set up
+    to and including that correction must match it — so the running net stays auditable and no
+    money is silently created or lost. Sets whose original is absent are handled by
+    :func:`check_correction_references`; this check only reconciles what is present.
+    """
+    # Decimals are stored as exact strings so the lookup state can live in a spillable map.
+    originals = index_factory()
+    for row in cost_and_usage:
+        if _is_correction(row):
+            continue
+        key = (row.get("x_ChargeKey") or "").strip()
+        cost = _dec(row.get("BilledCost"))
+        if key and cost is not None:
+            originals[key] = str(cost)
+
+    # Accumulate corrections per original in row order (running net is order-sensitive).
+    running = index_factory()
+    out: list[Diagnostic] = []
+    for i, row in enumerate(cost_and_usage, start=1):
+        if not _is_correction(row):
+            continue
+        ref = (row.get("x_CorrectionOf") or "").strip()
+        if ref not in originals:
+            continue  # missing original -> reported by check_correction_references
+        delta = _dec(row.get("BilledCost"))
+        if delta is None:
+            continue
+        base = running.get(ref) or originals[ref]
+        net = Decimal(base) + delta
+        running[ref] = str(net)
+        declared = _dec(row.get("x_NetCharge"))
+        if declared is None:
+            continue
+        if abs(net - declared) > tolerance:
+            out.append(
+                Diagnostic(
+                    code="FDT-CORR-002",
+                    severity=Severity.ERROR,
+                    message=f"correction set for {ref!r} nets to {net} but x_NetCharge "
+                    f"declares {declared}",
+                    datasets=("Cost and Usage",),
+                    dataset="Cost and Usage",
+                    line_number=i,
+                    column="x_NetCharge",
+                    expected=str(declared),
+                    actual=str(net),
+                    record_keys={"x_CorrectionOf": ref},
+                )
+            )
+    return out
+
+
+def check_correction_references(
+    cost_and_usage: RowStream, *, index_factory: IndexFactory = dict
+) -> list[Diagnostic]:
+    """A correction line's ``x_CorrectionOf`` must point at a still-present *original* charge.
+
+    The lookup is built only from non-correction originals, and a correction that references
+    its own key is rejected — otherwise a correction with ``x_ChargeKey == x_CorrectionOf`` and
+    no surviving original would pass, defeating the auditability guarantee.
+    """
+    original_keys = index_factory()
+    for r in cost_and_usage:
+        key = (r.get("x_ChargeKey") or "").strip()
+        if key and not _is_correction(r):
+            original_keys[key] = ""
+    out: list[Diagnostic] = []
+    for i, row in enumerate(cost_and_usage, start=1):
+        ref = (row.get("x_CorrectionOf") or "").strip()
+        if not ref:
+            continue
+        self_key = (row.get("x_ChargeKey") or "").strip()
+        if ref == self_key or ref not in original_keys:
+            out.append(
+                Diagnostic(
+                    code="FDT-CORR-001",
+                    severity=Severity.ERROR,
+                    message=f"correction row {i} references original charge {ref!r} that is not "
+                    "present as an original (original must remain auditable)",
+                    datasets=("Cost and Usage",),
+                    dataset="Cost and Usage",
+                    line_number=i,
+                    column="x_CorrectionOf",
+                    value=ref,
+                    record_keys={"x_CorrectionOf": ref},
+                )
+            )
+    return out