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

focus_data_toolkit/io/row_source.py

@@ -0,0 +1,117 @@
+"""Format-agnostic row input: open a CSV or Parquet source behind one protocol.
+
+Client exports arrive as CSV (possibly gzipped) or Parquet. :func:`open_row_source` detects
+the physical format — by the ``PAR1`` magic bytes first, extension as a fallback for
+unreadable paths — and returns the matching streaming reader. Both readers already share
+the same shape (``source_columns``, iteration yielding ``Record``, ``close``); the
+:class:`RowSource` protocol names that contract so conversion code can consume either
+without caring which it got.
+
+Parquet support requires the ``[parquet]`` extra; opening a Parquet file without it raises
+the same actionable :class:`~focus_data_toolkit.io.records.MalformedRecordError` install
+hint as Parquet output does.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from focus_data_toolkit.io.csv_io import CsvRowReader
+from focus_data_toolkit.io.records import MalformedRecordError, Record
+
+_PARQUET_MAGIC = b"PAR1"
+
+
+@runtime_checkable
+class RowSource(Protocol):
+    """A streaming, closeable source of rows with a known header."""
+
+    source_columns: tuple[str, ...]
+
+    def __iter__(self) -> Iterator[Record]: ...
+
+    def close(self) -> None: ...
+
+
+def is_parquet(path: str | os.PathLike[str]) -> bool:
+    """Whether ``path`` is a Parquet file (magic bytes; ``.parquet`` suffix as fallback)."""
+    p = Path(path)
+    try:
+        with open(p, "rb") as fh:
+            return fh.read(4) == _PARQUET_MAGIC
+    except OSError:
+        return p.suffix.lower() == ".parquet"
+
+
+def _hive_partition_columns(base_dir: Path) -> tuple[str, ...]:
+    """Partition column names of a Hive-layout directory, walking ``COL=value`` segments."""
+    cols: list[str] = []
+    current = base_dir
+    while True:
+        subdirs = [e for e in current.iterdir() if e.is_dir() and "=" in e.name]
+        if not subdirs:
+            return tuple(cols)
+        cols.append(subdirs[0].name.split("=", 1)[0])
+        current = subdirs[0]
+
+
+def open_row_source(path: str | os.PathLike[str], *, dataset: str | None = None) -> RowSource:
+    """Open ``path`` as a :class:`RowSource`, auto-detecting the physical format.
+
+    A file is sniffed as CSV (``.gz`` ok) or Parquet; a directory is read as a
+    Hive-partitioned Parquet dataset (partition columns inferred from the ``COL=value``
+    path segments). ``dataset`` optionally names the FOCUS dataset the file holds, letting
+    the Parquet readers render typed values by the right model columns instead of inferring
+    the dataset from the header overlap. CSV input ignores it (values are already strings).
+    """
+    p = Path(path)
+    if p.is_dir():
+        from focus_data_toolkit.io.parquet_io import PartitionedParquetReader
+
+        with _parquet_errors(p):
+            return PartitionedParquetReader(
+                p, dataset or "Cost and Usage", _hive_partition_columns(p)
+            )
+    if is_parquet(p):
+        from focus_data_toolkit.io.parquet_io import ParquetRowReader
+
+        with _parquet_errors(p):
+            return ParquetRowReader(p, dataset=dataset)
+    return CsvRowReader(p)
+
+
+@contextmanager
+def _parquet_errors(path: Path) -> Iterator[None]:
+    """Translate Arrow open/read failures into the CLI-friendly MalformedRecordError.
+
+    A missing-pyarrow MalformedRecordError (with its install hint) passes through untouched.
+    """
+    try:
+        yield
+    except MalformedRecordError:
+        raise
+    except (OSError, ValueError) as exc:
+        # pyarrow's ArrowInvalid/ArrowIOError derive from ValueError/OSError, so a corrupt
+        # or truncated Parquet file surfaces as a clean input error, never a traceback.
+        raise MalformedRecordError(f"cannot read Parquet source {path}: {exc}") from exc
+
+
+def read_source_rows(
+    path: str | os.PathLike[str], *, dataset: str | None = None
+) -> list[dict[str, str]]:
+    """Materialise a CSV/Parquet source into a list of dict rows (eager-path input)."""
+    reader = open_row_source(path, dataset=dataset)
+    try:
+        if isinstance(reader, CsvRowReader):
+            return [dict(record.values) for record in reader]
+        with _parquet_errors(Path(path)):  # iteration can hit mid-file corruption too
+            return [dict(record.values) for record in reader]
+    finally:
+        reader.close()
+
+
+__all__ = ["RowSource", "is_parquet", "open_row_source", "read_source_rows"]

focus_data_toolkit/lifecycle.py

@@ -0,0 +1,342 @@
+"""Dataset-instance snapshots and billing/invoice lifecycle-chain rules (P1.10).
+
+A **dataset instance** is one delivered snapshot of a FOCUS dataset for a subject (an invoice,
+a billing period): who it is, when it was created / last updated, whether it is complete, the
+period it covers, its lifecycle status, and which instance preceded it. Real client pipelines
+*record* these (they are never fabricated for client data); the toolkit models them so a
+sequence of snapshots can be checked for illegal status transitions — e.g. a ``Voided`` invoice
+must not silently go back to ``Issued``, an ``Issued`` invoice must not revert to ``Open``.
+
+The allowed transitions come straight from the FOCUS ``InvoiceIssueStatus`` (``Open`` →
+``Issued`` → ``Voided``) and ``BillingPeriodStatus`` (``Open`` → ``Closed``) value sets; a
+correction is a *new* instance/line, never an in-place edit of a closed/issued one.
+
+Beyond transitions, :func:`check_instance_chains` validates the chain structure itself —
+``instance_id`` / per-subject ``order`` uniqueness (FDT-LIFE-001/002),
+``previous_instance_id`` resolution (FDT-LIFE-003), cycle detection (FDT-LIFE-004),
+``last_updated`` monotonicity (FDT-LIFE-005), and closed-instance immutability
+(FDT-LIFE-006) — all as structured diagnostics. :func:`check_dataset_instances` runs the
+whole battery (chains + status transitions) in one call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+
+from focus_data_toolkit.errors import Diagnostic, Severity
+
+# Allowed forward transitions (a status may also stay the same — an idempotent re-delivery).
+INVOICE_TRANSITIONS: dict[str, frozenset[str]] = {
+    "Open": frozenset({"Open", "Issued", "Voided"}),
+    "Issued": frozenset({"Issued", "Voided"}),
+    "Voided": frozenset({"Voided"}),
+}
+BILLING_PERIOD_TRANSITIONS: dict[str, frozenset[str]] = {
+    "Open": frozenset({"Open", "Closed"}),
+    "Closed": frozenset({"Closed"}),
+}
+
+
+@dataclass(frozen=True)
+class DatasetInstance:
+    """One recorded snapshot of a dataset for a subject (invoice / billing period)."""
+
+    instance_id: str
+    dataset: str
+    subject_id: str
+    order: int
+    created: str
+    last_updated: str
+    complete: bool
+    period_start: str
+    period_end: str
+    status: str
+    previous_instance_id: str | None = None
+
+
+def _check_transitions(
+    instances: Sequence[DatasetInstance], allowed: dict[str, frozenset[str]]
+) -> list[Diagnostic]:
+    """Flag any status change not permitted by ``allowed`` between consecutive snapshots.
+
+    Snapshots are grouped by ``subject_id`` and ordered by ``order``; each adjacent pair is a
+    transition. An unknown status value is left to the per-dataset linter (allowed-value check).
+    """
+    by_subject: dict[str, list[DatasetInstance]] = {}
+    for inst in instances:
+        by_subject.setdefault(inst.subject_id, []).append(inst)
+
+    out: list[Diagnostic] = []
+    for subject, snaps in sorted(by_subject.items()):
+        ordered = sorted(snaps, key=lambda s: s.order)
+        for prev, cur in zip(ordered, ordered[1:], strict=False):
+            permitted = allowed.get(prev.status)
+            if permitted is None or cur.status not in permitted:
+                out.append(
+                    Diagnostic(
+                        code="FDT-CORR-004",
+                        severity=Severity.ERROR,
+                        message=f"illegal status transition {prev.status!r} -> {cur.status!r} "
+                        f"for {subject!r} (instances {prev.instance_id} -> {cur.instance_id})",
+                        datasets=(cur.dataset,),
+                        dataset=cur.dataset,
+                        record_keys={"subject_id": subject},
+                        expected=f"one of {sorted(permitted)}" if permitted else "known status",
+                        actual=cur.status,
+                        context={"from_instance": prev.instance_id, "to_instance": cur.instance_id},
+                    )
+                )
+    return out
+
+
+def check_invoice_status_transitions(instances: Iterable[DatasetInstance]) -> list[Diagnostic]:
+    """Validate Invoice Detail status transitions across dataset instances (FDT-CORR-004)."""
+    invoices = [i for i in instances if i.dataset == "Invoice Detail"]
+    return _check_transitions(invoices, INVOICE_TRANSITIONS)
+
+
+def check_billing_period_status_transitions(
+    instances: Iterable[DatasetInstance],
+) -> list[Diagnostic]:
+    """Validate Billing Period status transitions across dataset instances (FDT-CORR-004)."""
+    periods = [i for i in instances if i.dataset == "Billing Period"]
+    return _check_transitions(periods, BILLING_PERIOD_TRANSITIONS)
+
+
+def check_status_transitions(instances: Iterable[DatasetInstance]) -> list[Diagnostic]:
+    """Validate both invoice and billing-period status transitions in one pass."""
+    instances = list(instances)
+    return check_invoice_status_transitions(instances) + check_billing_period_status_transitions(
+        instances
+    )
+
+
+# Statuses after which a subject's recorded facts are frozen: later snapshots may re-deliver
+# or move forward in status, but must not rewrite the period or un-complete the data.
+_CLOSED_STATUSES: frozenset[str] = frozenset({"Closed", "Issued", "Voided"})
+
+
+def _parse_dt(value: str) -> datetime | None:
+    """Parse a FOCUS Date/Time; naive or malformed values return None (the linter's job)."""
+    try:
+        parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo is not None else None
+
+
+def _chain_diag(
+    code: str, message: str, inst: DatasetInstance, **extra: object
+) -> Diagnostic:
+    return Diagnostic(
+        code=code,
+        severity=Severity.ERROR,
+        message=message,
+        datasets=(inst.dataset,),
+        dataset=inst.dataset,
+        record_keys={"subject_id": inst.subject_id, "instance_id": inst.instance_id},
+        **extra,  # type: ignore[arg-type]
+    )
+
+
+def check_instance_chains(instances: Iterable[DatasetInstance]) -> list[Diagnostic]:
+    """Validate the structure of dataset-instance chains (FDT-LIFE-001..006).
+
+    * **FDT-LIFE-001** — ``instance_id`` is reused across snapshots.
+    * **FDT-LIFE-002** — two snapshots of one subject share the same ``order``.
+    * **FDT-LIFE-003** — ``previous_instance_id`` does not resolve to an existing earlier
+      snapshot (unknown id, self-reference, or non-decreasing order). Cross-subject and
+      cross-dataset links are legitimate delivery lineage (e.g. a replacement invoice
+      points at the voided one it replaces).
+    * **FDT-LIFE-004** — the ``previous_instance_id`` links form a cycle.
+    * **FDT-LIFE-005** — ``last_updated`` is before ``created``, or decreases between
+      consecutive snapshots of a subject (history must move forward).
+    * **FDT-LIFE-006** — a snapshot after a closed/issued/voided one rewrites the recorded
+      period, or flips ``complete`` back to ``False`` (closed instances are immutable;
+      a correction is a new line, never an in-place edit).
+
+    Unknown status values and malformed timestamps are left to the per-dataset linter.
+    """
+    snaps = list(instances)
+    out: list[Diagnostic] = []
+
+    by_id: dict[str, DatasetInstance] = {}
+    for inst in snaps:
+        if inst.instance_id in by_id:
+            out.append(
+                _chain_diag(
+                    "FDT-LIFE-001",
+                    f"instance_id {inst.instance_id!r} is reused "
+                    f"(subjects {by_id[inst.instance_id].subject_id!r} and {inst.subject_id!r})",
+                    inst,
+                    value=inst.instance_id,
+                )
+            )
+        else:
+            by_id[inst.instance_id] = inst
+
+    by_subject: dict[tuple[str, str], list[DatasetInstance]] = {}
+    for inst in snaps:
+        by_subject.setdefault((inst.dataset, inst.subject_id), []).append(inst)
+
+    for (_dataset, subject), group in sorted(by_subject.items()):
+        seen_orders: dict[int, DatasetInstance] = {}
+        for inst in group:
+            if inst.order in seen_orders:
+                out.append(
+                    _chain_diag(
+                        "FDT-LIFE-002",
+                        f"snapshots {seen_orders[inst.order].instance_id!r} and "
+                        f"{inst.instance_id!r} of {subject!r} share order {inst.order}",
+                        inst,
+                        actual=str(inst.order),
+                    )
+                )
+            else:
+                seen_orders[inst.order] = inst
+
+        ordered = sorted(group, key=lambda s: (s.order, s.instance_id))
+
+        # previous_instance_id resolution.
+        for inst in ordered:
+            prev_id = inst.previous_instance_id
+            if prev_id is None:
+                continue
+            prev = by_id.get(prev_id)
+            if prev is None or prev_id == inst.instance_id:
+                reason = "references itself" if prev_id == inst.instance_id else "is unknown"
+                out.append(
+                    _chain_diag(
+                        "FDT-LIFE-003",
+                        f"previous_instance_id {prev_id!r} of {inst.instance_id!r} {reason}",
+                        inst,
+                        value=prev_id,
+                    )
+                )
+            elif prev.order >= inst.order:
+                out.append(
+                    _chain_diag(
+                        "FDT-LIFE-003",
+                        f"previous_instance_id {prev_id!r} of {inst.instance_id!r} does not "
+                        f"precede it (order {prev.order} >= {inst.order})",
+                        inst,
+                        value=prev_id,
+                    )
+                )
+
+        # last_updated monotonicity along the delivery sequence.
+        prev_updated: datetime | None = None
+        prev_inst: DatasetInstance | None = None
+        for inst in ordered:
+            created, updated = _parse_dt(inst.created), _parse_dt(inst.last_updated)
+            if created is not None and updated is not None and updated < created:
+                out.append(
+                    _chain_diag(
+                        "FDT-LIFE-005",
+                        f"last_updated of {inst.instance_id!r} precedes its created",
+                        inst,
+                        expected=f">= {inst.created}",
+                        actual=inst.last_updated,
+                    )
+                )
+            if updated is not None:
+                if prev_updated is not None and updated < prev_updated:
+                    assert prev_inst is not None
+                    out.append(
+                        _chain_diag(
+                            "FDT-LIFE-005",
+                            f"last_updated moves backwards between {prev_inst.instance_id!r} "
+                            f"and {inst.instance_id!r} of {subject!r}",
+                            inst,
+                            expected=f">= {prev_inst.last_updated}",
+                            actual=inst.last_updated,
+                        )
+                    )
+                prev_updated, prev_inst = updated, inst
+
+        # Closed-instance immutability: once closed/issued/voided, the recorded period is
+        # frozen and completeness must not regress.
+        frozen: DatasetInstance | None = None
+        for inst in ordered:
+            if frozen is not None:
+                if (inst.period_start, inst.period_end) != (
+                    frozen.period_start,
+                    frozen.period_end,
+                ):
+                    out.append(
+                        _chain_diag(
+                            "FDT-LIFE-006",
+                            f"{inst.instance_id!r} rewrites the period of {subject!r} recorded "
+                            f"by closed snapshot {frozen.instance_id!r}",
+                            inst,
+                            expected=f"{frozen.period_start}/{frozen.period_end}",
+                            actual=f"{inst.period_start}/{inst.period_end}",
+                        )
+                    )
+                if frozen.complete and not inst.complete:
+                    out.append(
+                        _chain_diag(
+                            "FDT-LIFE-006",
+                            f"{inst.instance_id!r} flips {subject!r} back to incomplete after "
+                            f"closed snapshot {frozen.instance_id!r}",
+                            inst,
+                            expected="complete=True",
+                            actual="complete=False",
+                        )
+                    )
+            if frozen is None and inst.status in _CLOSED_STATUSES:
+                frozen = inst
+
+    out.extend(_check_cycles(snaps, by_id))
+    return out
+
+
+def _check_cycles(
+    snaps: Sequence[DatasetInstance], by_id: dict[str, DatasetInstance]
+) -> list[Diagnostic]:
+    """Detect cycles in the ``previous_instance_id`` graph (each reported once)."""
+    out: list[Diagnostic] = []
+    state: dict[str, int] = {}  # 0 = visiting, 1 = done
+    for start in sorted(by_id):
+        if start in state:
+            continue
+        path: list[str] = []
+        current: str | None = start
+        while current is not None and current in by_id and current not in state:
+            state[current] = 0
+            path.append(current)
+            current = by_id[current].previous_instance_id
+        if current is not None and state.get(current) == 0:
+            cycle = path[path.index(current):]
+            inst = by_id[current]
+            out.append(
+                _chain_diag(
+                    "FDT-LIFE-004",
+                    "previous_instance_id links form a cycle: " + " -> ".join([*cycle, current]),
+                    inst,
+                    context={"cycle": ",".join(cycle)},
+                )
+            )
+        for node in path:
+            state[node] = 1
+    return out
+
+
+def check_dataset_instances(instances: Iterable[DatasetInstance]) -> list[Diagnostic]:
+    """Run the full lifecycle battery: chain structure plus status transitions."""
+    snaps = list(instances)
+    return check_instance_chains(snaps) + check_status_transitions(snaps)
+
+
+__all__ = [
+    "BILLING_PERIOD_TRANSITIONS",
+    "INVOICE_TRANSITIONS",
+    "DatasetInstance",
+    "check_billing_period_status_transitions",
+    "check_dataset_instances",
+    "check_instance_chains",
+    "check_invoice_status_transitions",
+    "check_status_transitions",
+]

focus_data_toolkit/manifest.py

@@ -0,0 +1,114 @@
+"""Deterministic, machine-readable conversion manifest.
+
+The manifest records, per FOCUS 1.4 dataset, whether it was produced and — column by
+column — how each value was obtained (see :mod:`focus_data_toolkit.provenance`). It is
+built without a clock or RNG so a given conversion always yields the same manifest bytes.
+Any produced column with ``ASSUMED`` lineage sets ``assumptions_present`` and prevents a
+full-conformance claim.
+"""
+
+from __future__ import annotations
+
+import json
+
+from focus_data_toolkit.provenance import ColumnRule
+
+MANIFEST_FILENAME = "focus_1_4_manifest.json"
+TARGET_VERSION = "1.4"
+
+# Dataset statuses.
+PRODUCED = "PRODUCED"
+PRODUCED_SYNTHETIC = "PRODUCED_SYNTHETIC"
+NOT_PRODUCED = "NOT_PRODUCED"
+
+# Conformance labels (never "fully conformant": see model/validator.py levels).
+CONF_STRUCTURAL_LINT = "STRUCTURAL_LINT"  # produced from factual lineage, passed the lint
+CONF_LINT_FAILED = "LINT_FAILED"          # produced from factual lineage, but the lint failed
+CONF_NOT_VALIDATED = "NOT_VALIDATED"      # produced but lint not run (validate=False)
+CONF_SYNTHETIC = "SYNTHETIC"              # produced with assumed values
+CONF_INCOMPLETE = "INCOMPLETE"            # not produced
+
+
+def dataset_entry(
+    *,
+    status: str,
+    conformance: str,
+    provenance: dict[str, ColumnRule],
+    row_count: int | None = None,
+    reason: str | None = None,
+    blocking_columns: list[str] | None = None,
+    output_file: str | None = None,
+    partitioned_by: list[str] | None = None,
+    lineage_summary: dict[str, dict[str, int]] | None = None,
+) -> dict:
+    entry: dict = {
+        "status": status,
+        "conformance": conformance,
+        "columns": {col: provenance[col].as_dict() for col in sorted(provenance)},
+    }
+    if row_count is not None:
+        entry["row_count"] = row_count
+    if lineage_summary:
+        # Per-value lineage counts for columns whose rule varies by row: the headline
+        # column lineage above stays the weakest category, this shows the actual mix.
+        entry["lineage_summary"] = lineage_summary
+    if reason:
+        entry["reason"] = reason
+    if blocking_columns:
+        entry["blocking_columns"] = blocking_columns
+    if output_file:
+        entry["output_file"] = output_file
+    if partitioned_by:
+        # Present only for a Hive-partitioned Parquet dataset: output_file is the dataset
+        # directory, partitioned on these columns (a reader reconstructs them from the paths).
+        entry["partitioned_by"] = partitioned_by
+    return entry
+
+
+def build_manifest(
+    *,
+    tool_version: str,
+    source_version: str,
+    mode: str,
+    datasets: dict[str, dict],
+    detection: dict | None = None,
+    contexts: dict | None = None,
+    diagnostics: list[dict] | None = None,
+    capability_profile: dict | None = None,
+    supplements: list[dict] | None = None,
+) -> dict:
+    assumptions_present = any(
+        entry["status"] in (PRODUCED, PRODUCED_SYNTHETIC)
+        and any(col.get("lineage") == "ASSUMED" for col in entry.get("columns", {}).values())
+        for entry in datasets.values()
+    )
+    manifest: dict = {
+        "tool_version": tool_version,
+        "source_version": source_version,
+        "target_version": TARGET_VERSION,
+        "mode": mode,
+        "assumptions_present": assumptions_present,
+        "datasets": datasets,
+    }
+    # Detection decision and per-row context summary are part of the deterministic business
+    # record (no clock/RNG). Diagnostics record non-fatal findings (e.g. ambiguous context).
+    if detection is not None:
+        manifest["detection"] = detection
+    if contexts is not None:
+        manifest["contexts"] = contexts
+    if diagnostics is not None:
+        manifest["diagnostics"] = diagnostics
+    if capability_profile is not None:
+        # The applicability conditions the lint actually enforced. Recorded even when
+        # empty ("none-declared"), so an unevaluated condition set is never silent.
+        manifest["capability_profile"] = capability_profile
+    if supplements:
+        # Client-supplied fact files (path, kind, sha256, row counts, declared
+        # provenance): the audit trail behind every ENRICHED column.
+        manifest["supplements"] = supplements
+    return manifest
+
+
+def render(manifest: dict) -> str:
+    """Serialize the manifest to deterministic JSON bytes-as-text (sorted, trailing LF)."""
+    return json.dumps(manifest, indent=2, sort_keys=True) + "\n"

focus_data_toolkit/model/__init__.py

@@ -0,0 +1,43 @@
+"""FOCUS 1.4 data model (committed JSON artifact) and helpers.
+
+The model is derived from the FinOps Foundation "FOCUS 1.4 Data Model"
+workbook (https://focus.finops.org) by ``tools/extract_focus_1_4_model.py``;
+the JSON is the artifact of record for this package.
+"""
+
+from __future__ import annotations
+
+from focus_data_toolkit.model.validator import (
+    lint_focus_1_4_structure,
+    load_model,
+    resolve_dataset,
+    validate_focus_1_4,
+)
+
+FOCUS_1_4_DATASETS: tuple[str, ...] = (
+    "Cost and Usage",
+    "Contract Commitment",
+    "Billing Period",
+    "Invoice Detail",
+)
+
+
+def dataset_columns(dataset: str) -> tuple[str, ...]:
+    """Return the FOCUS 1.4 column names of ``dataset``, in model order."""
+    return tuple(load_model()["datasets"][resolve_dataset(dataset)]["columns"])
+
+
+def column_spec(dataset: str, column: str) -> dict:
+    """Return the model spec of one column (feature_level, allows_nulls, ...)."""
+    return load_model()["datasets"][resolve_dataset(dataset)]["columns"][column]
+
+
+__all__ = [
+    "FOCUS_1_4_DATASETS",
+    "column_spec",
+    "dataset_columns",
+    "lint_focus_1_4_structure",
+    "load_model",
+    "resolve_dataset",
+    "validate_focus_1_4",
+]

focus_data_toolkit/model/capabilities.py

@@ -0,0 +1,66 @@
+"""Capability profile — which FOCUS applicability conditions a source supports.
+
+Several FOCUS columns are only *conditionally* required (e.g. ``SkuId`` /
+``SkuPriceId`` when the provider supports unit pricing). The linter can only
+enforce those requirements when the caller declares which conditions apply; an
+undeclared condition is **not evaluated**, never silently assumed either way.
+
+A :class:`CapabilityProfile` makes that declaration explicit and auditable: the
+conversion pipeline records the active profile in the manifest, so a clean lint
+can always be read together with the exact set of conditions it enforced.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from focus_data_toolkit.model.validator import (
+    COND_MULTIPLE_PRICING_CATEGORIES,
+    COND_UNIT_PRICING,
+)
+
+# All applicability conditions the linter knows how to enforce.
+KNOWN_CONDITIONS: frozenset[str] = frozenset(
+    {COND_MULTIPLE_PRICING_CATEGORIES, COND_UNIT_PRICING}
+)
+
+
+@dataclass(frozen=True)
+class CapabilityProfile:
+    """An explicit, validated declaration of supported applicability conditions.
+
+    ``source`` documents where the declaration came from (e.g. ``"cli"``,
+    ``"api"``); the default profile declares nothing and is labelled
+    ``"none-declared"`` so an unevaluated condition set is visible, not silent.
+    """
+
+    supported_conditions: frozenset[str] = field(default_factory=frozenset)
+    source: str = "none-declared"
+
+    def __post_init__(self) -> None:
+        # Accept any iterable-of-str the caller passed and materialize it exactly once —
+        # a one-shot generator must not be exhausted by validation before it is frozen.
+        conditions = frozenset(self.supported_conditions)
+        object.__setattr__(self, "supported_conditions", conditions)
+        unknown = conditions - KNOWN_CONDITIONS
+        if unknown:
+            known = ", ".join(sorted(KNOWN_CONDITIONS))
+            raise ValueError(
+                f"unknown applicability condition(s) {sorted(unknown)}; known: {known}"
+            )
+
+    @classmethod
+    def none(cls) -> CapabilityProfile:
+        """The default profile: no condition declared (none enforced)."""
+        return cls()
+
+    @classmethod
+    def of(cls, *conditions: str, source: str = "api") -> CapabilityProfile:
+        return cls(frozenset(conditions), source)
+
+    def as_dict(self) -> dict:
+        """Deterministic manifest payload."""
+        return {
+            "supported_conditions": sorted(self.supported_conditions),
+            "source": self.source,
+        }