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

focus_data_toolkit/studio/security.py

@@ -0,0 +1,125 @@
+"""Security helpers for the local Studio.
+
+Even a loopback-only server is reachable by a malicious web page open in the same browser, so the
+Studio defends the surface with (a) a per-start random token required on every API call,
+(b) strict ``Host`` header validation (anti DNS-rebinding), (c) ``Origin`` validation on
+state-changing requests (anti-CSRF), and (d) confinement of all file access to an allowlisted
+root. All checks are standard-library only.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+import secrets
+from pathlib import Path
+
+
+def new_token() -> str:
+    """A fresh URL-safe token, generated once per server start."""
+    return secrets.token_urlsafe(32)
+
+
+def token_matches(expected: str, provided: str | None) -> bool:
+    """Constant-time token comparison; ``False`` for a missing/empty token."""
+    if not provided:
+        return False
+    return hmac.compare_digest(expected, provided)
+
+
+def is_loopback_host(host: str) -> bool:
+    """Whether a *bind* address is loopback (so remote exposure needs an explicit opt-in)."""
+    h = (host or "").strip().lower()
+    if h in ("localhost", "::1", "0:0:0:0:0:0:0:1"):
+        return True
+    return h.startswith("127.")
+
+
+def allowed_authorities(host: str, port: int) -> set[str]:
+    """The set of acceptable ``Host`` header values (``authority`` = host[:port])."""
+    hosts = {"127.0.0.1", "localhost", "[::1]", "::1"}
+    if host:
+        hosts.add(host)
+        hosts.add(f"[{host}]")
+    out: set[str] = set()
+    for h in hosts:
+        out.add(h.lower())
+        out.add(f"{h}:{port}".lower())
+    return out
+
+
+def host_header_allowed(host_header: str | None, host: str, port: int) -> bool:
+    """Validate the ``Host`` header against the loopback/bind allowlist (anti DNS-rebinding)."""
+    if not host_header:
+        return False
+    return host_header.strip().lower() in allowed_authorities(host, port)
+
+
+def allowed_origins(host: str, port: int) -> set[str]:
+    """Acceptable ``Origin`` values for state-changing requests (same-origin only)."""
+    return {f"http://{authority}" for authority in allowed_authorities(host, port)}
+
+
+def origin_allowed(origin: str | None, host: str, port: int) -> bool:
+    """Validate an ``Origin`` header (anti-CSRF). A missing Origin on a POST is rejected."""
+    if not origin:
+        return False
+    return origin.strip().lower() in allowed_origins(host, port)
+
+
+class PathOutsideRoot(ValueError):
+    """Raised when a requested path escapes the allowlisted root directory."""
+
+
+def resolve_within_root(user_path: str, root: Path) -> Path:
+    """Resolve ``user_path`` to an existing entry whose *physical* location stays under ``root``.
+
+    ``root`` is always a server-controlled directory (never user input). The path is walked one
+    component at a time and confined on two levels:
+
+    * **Lexically** — absolute inputs, drive-relative / UNC paths and any ``..`` segment are
+      refused, and each component is matched **by name** against the actual entries of the current
+      directory (via :func:`os.scandir`), so the user string never participates in path
+      construction (only in an equality comparison).
+    * **Physically** — the matched entry is canonicalised with :meth:`Path.resolve` (which follows
+      symlinks, Windows junctions and reparse points) and must remain *at or under* the canonical
+      root (:meth:`Path.is_relative_to`, not a textual prefix check) **before** the walk descends
+      into it. A link whose real target escapes the root is therefore rejected — a link that stays
+      inside the root is followed and accepted.
+
+    Nested browsing (``a/b/c.csv``) is fully supported. A component with no matching entry, a broken
+    link, a symlink loop or an inaccessible/missing root all raise :class:`PathOutsideRoot`; the
+    returned path is fully canonical (all links already resolved). No user-controlled data reaches a
+    filesystem operation.
+    """
+    if os.path.isabs(user_path) or user_path[:1] in ("/", "\\") or os.path.splitdrive(user_path)[0]:
+        raise PathOutsideRoot(f"absolute paths are not allowed: {user_path!r}")
+    try:
+        base = Path(root).resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise PathOutsideRoot("allowed root is not accessible") from exc
+    current = base
+    for raw in user_path.replace("\\", "/").split("/"):
+        if raw in ("", "."):
+            continue
+        if raw == "..":
+            raise PathOutsideRoot(f"path {user_path!r} is outside the allowed root")
+        match: Path | None = None
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    if entry.name == raw:
+                        match = Path(entry.path)
+                        break
+        except OSError as exc:
+            raise PathOutsideRoot(f"cannot resolve {user_path!r} under the allowed root") from exc
+        if match is None:
+            raise PathOutsideRoot(f"no entry {raw!r} under the allowed root")
+        try:
+            resolved = match.resolve(strict=True)
+        except (OSError, RuntimeError) as exc:  # broken link, symlink loop, permission denied, ...
+            raise PathOutsideRoot(f"cannot resolve {user_path!r} under the allowed root") from exc
+        if not resolved.is_relative_to(base):
+            raise PathOutsideRoot(f"path {user_path!r} is outside the allowed root")
+        current = resolved
+    return current

focus_data_toolkit/studio/server.py

@@ -0,0 +1,71 @@
+"""Launch the Studio web server (uvicorn), loopback-only unless explicitly allowed."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+import threading
+import webbrowser
+from pathlib import Path
+
+from focus_data_toolkit.studio.app import create_app
+from focus_data_toolkit.studio.config import (
+    DEFAULT_MAX_GENERATE_ROWS,
+    DEFAULT_MAX_UPLOAD_BYTES,
+    DEFAULT_PORT,
+    StudioConfig,
+)
+from focus_data_toolkit.studio.security import is_loopback_host
+
+
+def run(
+    *,
+    host: str = "127.0.0.1",
+    port: int = DEFAULT_PORT,
+    root: str | Path | None = None,
+    work_dir: str | Path | None = None,
+    allow_remote: bool = False,
+    open_browser: bool = True,
+    max_upload_bytes: int = DEFAULT_MAX_UPLOAD_BYTES,
+    max_generate_rows: int = DEFAULT_MAX_GENERATE_ROWS,
+) -> int:
+    """Start the Studio. Refuses a non-loopback bind unless ``allow_remote`` is set."""
+    if not is_loopback_host(host) and not allow_remote:
+        print(
+            f"error: refusing to bind non-loopback host {host!r} without --allow-remote "
+            "(the Studio serves local files; expose it only on trusted networks)",
+            file=sys.stderr,
+        )
+        return 2
+    if work_dir is None:
+        work_dir = Path(tempfile.mkdtemp(prefix="fdt-studio-"))
+    config = StudioConfig(
+        host=host,
+        port=port,
+        root=Path(root) if root else Path.cwd(),
+        work_dir=Path(work_dir),
+        allow_remote=allow_remote,
+        max_upload_bytes=max_upload_bytes,
+        max_generate_rows=max_generate_rows,
+    )
+    app = create_app(config)
+    url = config.url()
+    print(f"Focus Data Toolkit Studio: {url}")
+    print(f"  root: {config.root}")
+    print(f"  work: {config.work_dir}")
+    if not is_loopback_host(host):
+        print("  WARNING: bound to a non-loopback address — the access token is the only guard.")
+    if open_browser:
+        threading.Timer(1.0, lambda: _open(url)).start()
+
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port, log_level="warning")
+    return 0
+
+
+def _open(url: str) -> None:
+    try:
+        webbrowser.open(url)
+    except Exception:  # a headless environment has no browser — never fatal
+        pass

focus_data_toolkit/supplement/__init__.py

@@ -0,0 +1,50 @@
+"""Supplemental client data: complete a FOCUS 1.2/1.3 source into factual 1.4 datasets.
+
+A Cost and Usage source alone cannot factually populate the provider-issued facts the
+FOCUS 1.4 Billing Period / Invoice Detail / Contract Commitment datasets require. This
+package lets a client supply those facts:
+
+* :mod:`focus_data_toolkit.supplement.gaps` — compute exactly which columns are missing
+  for a given source (the ``gaps`` CLI command) and which supplement satisfies each;
+* :mod:`focus_data_toolkit.supplement.kinds` — the registry of supplement kinds (their
+  target dataset, join keys and allowed fact columns);
+* :mod:`focus_data_toolkit.supplement.adapters` — provider-native adapters that translate
+  documented AWS / Azure / GCP export formats into those kinds automatically.
+
+Supplied values carry ``ENRICHED`` lineage with full attribution, so a fully covered
+dataset becomes strictly producible without any code change to the strict gate.
+"""
+
+from __future__ import annotations
+
+from focus_data_toolkit.supplement.gaps import ColumnGap, GapReport, compute_gaps
+from focus_data_toolkit.supplement.kinds import SUPPLEMENT_KINDS, SupplementKind
+from focus_data_toolkit.supplement.loader import SupplementBundle, SupplementTable
+from focus_data_toolkit.supplement.spec import (
+    SupplementError,
+    SupplementFileSpec,
+    load_bundle_dir,
+    parse_supplement_arg,
+)
+from focus_data_toolkit.supplement.validate import (
+    SourceKeySets,
+    source_key_sets,
+    validate_supplements,
+)
+
+__all__ = [
+    "SUPPLEMENT_KINDS",
+    "ColumnGap",
+    "GapReport",
+    "SourceKeySets",
+    "SupplementBundle",
+    "SupplementError",
+    "SupplementFileSpec",
+    "SupplementKind",
+    "SupplementTable",
+    "compute_gaps",
+    "load_bundle_dir",
+    "parse_supplement_arg",
+    "source_key_sets",
+    "validate_supplements",
+]

focus_data_toolkit/supplement/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""Provider-native supplement adapters (AWS / Azure / GCP export formats)."""
+
+from __future__ import annotations
+
+from focus_data_toolkit.supplement.adapters.registry import (
+    Adapter,
+    AdapterError,
+    adapter_provenance,
+    detect_adapter,
+    get_adapter,
+    load_adapters,
+)
+
+__all__ = [
+    "Adapter",
+    "AdapterError",
+    "adapter_provenance",
+    "detect_adapter",
+    "get_adapter",
+    "load_adapters",
+]

focus_data_toolkit/supplement/adapters/adapters_provenance.json

@@ -0,0 +1,39 @@
+{
+  "description": "Provenance of the vendored provider-native supplement adapters.",
+  "attribution": "Field names are derived from the official provider API documentation and the referenced open-source service models (botocore, Apache-2.0). Mapping tables authored for focus-data-toolkit.",
+  "retrieved": "2026-07-17",
+  "adapters": [
+    {
+      "file": "aws_invoice_summary.json",
+      "adapter": "aws-invoice-summary",
+      "target_kind": "invoice",
+      "source": "AWS Invoicing API \u2014 InvoiceSummary (ListInvoiceSummaries)",
+      "doc_url": "https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_invoicing_InvoiceSummary.html",
+      "sha256": "f69d31914694e9cfd7f9ec3be3aff273d2340a4f8368285d86c31cb6963ee0ae"
+    },
+    {
+      "file": "aws_savings_plans.json",
+      "adapter": "aws-savings-plans",
+      "target_kind": "contract_commitment",
+      "source": "AWS Savings Plans API \u2014 SavingsPlan (DescribeSavingsPlans)",
+      "doc_url": "https://docs.aws.amazon.com/savingsplans/latest/APIReference/API_SavingsPlan.html",
+      "sha256": "baf099ba17753672c52ba504d9deef978c279c4a168c8be72b05501a878df6fb"
+    },
+    {
+      "file": "azure_invoice.json",
+      "adapter": "azure-invoice",
+      "target_kind": "invoice",
+      "source": "Azure Billing \u2014 Invoices REST API (Invoice resource)",
+      "doc_url": "https://learn.microsoft.com/en-us/rest/api/billing/invoices/get?view=rest-billing-2024-04-01",
+      "sha256": "3539beba9d84cab5ae7fa8f7e2c35fb32d3c333e85a01ff887748ad6a4780e85"
+    },
+    {
+      "file": "gcp_compute_commitments.json",
+      "adapter": "gcp-compute-commitments",
+      "target_kind": "contract_commitment",
+      "source": "Google Compute Engine \u2014 regionCommitments (Commitment resource)",
+      "doc_url": "https://docs.cloud.google.com/compute/docs/reference/rest/v1/regionCommitments",
+      "sha256": "8adc15b222114ef6f90deca05aad448018b56a2a7214c4013a9e36039bb34ac3"
+    }
+  ]
+}

focus_data_toolkit/supplement/adapters/aws_invoice_summary.json

@@ -0,0 +1,24 @@
+{
+  "adapter": "aws-invoice-summary",
+  "version": "1",
+  "target_kind": "invoice",
+  "provenance": {
+    "source": "AWS Invoicing API — InvoiceSummary (ListInvoiceSummaries)",
+    "doc_url": "https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/API_invoicing_InvoiceSummary.html",
+    "field_names_from": "botocore invoicing service model, apiVersion 2024-12-01",
+    "retrieved": "2026-07-17",
+    "notes": "Invoice-header facts only. AWS does not expose payment terms on the invoice summary, so PaymentTerms is left for the client (coverage reporting shows the residual gap). Rows returned by the API are issued invoices, so InvoiceIssueStatus is the invariant 'Issued'. JSON nested fields are addressed by dot-path (Entity.InvoicingEntity, BillingPeriod.Month)."
+  },
+  "detect": {
+    "all_of": ["InvoiceId", "IssuedDate"],
+    "any_of": ["DueDate", "InvoiceType", "Entity.InvoicingEntity", "PurchaseOrderNumber"]
+  },
+  "fields": [
+    {"target": "InvoiceId", "source": "InvoiceId"},
+    {"target": "InvoiceIssuerName", "source": "Entity.InvoicingEntity"},
+    {"target": "InvoiceIssueDate", "source": "IssuedDate", "transform": "date_to_utc"},
+    {"target": "PaymentDueDate", "source": "DueDate", "transform": "date_to_utc"},
+    {"target": "PurchaseOrderNumber", "source": "PurchaseOrderNumber"},
+    {"target": "InvoiceIssueStatus", "const": "Issued"}
+  ]
+}

focus_data_toolkit/supplement/adapters/aws_savings_plans.json

@@ -0,0 +1,31 @@
+{
+  "adapter": "aws-savings-plans",
+  "version": "1",
+  "target_kind": "contract_commitment",
+  "provenance": {
+    "source": "AWS Savings Plans API — SavingsPlan (DescribeSavingsPlans)",
+    "doc_url": "https://docs.aws.amazon.com/savingsplans/latest/APIReference/API_SavingsPlan.html",
+    "field_names_from": "botocore savingsplans service model, apiVersion 2019-06-28",
+    "retrieved": "2026-07-17",
+    "notes": "Maps only fields genuinely determinable from a Savings Plans inventory. paymentOption uses the same vocabulary as FOCUS ContractCommitmentPaymentModel. The three constants are invariant facts of the Savings Plans product: it is a discount commitment (BenefitCategory=Discount), applies continuously to eligible usage (Model=Continuous), and commits to an hourly spend rate (FulfillmentInterval=Hourly). ContractCommitmentLastUpdated and ContractCommitmentApplicability are NOT emitted (not present in the export) — the client supplies them and coverage reporting shows the residual gap. OfferCategory is left out because a Savings Plan may be public or under a negotiated agreement, which the export does not distinguish."
+  },
+  "detect": {
+    "all_of": ["savingsPlanId", "paymentOption"],
+    "any_of": ["state", "savingsPlanType", "commitment", "start"]
+  },
+  "fields": [
+    {"target": "ContractCommitmentId", "source": "savingsPlanId"},
+    {"target": "ContractCommitmentPaymentModel", "source": "paymentOption",
+     "value_map": {"No Upfront": "No Upfront", "Partial Upfront": "Partial Upfront", "All Upfront": "All Upfront"}},
+    {"target": "ContractCommitmentPaymentInterval", "source": "paymentOption",
+     "value_map": {"All Upfront": "One-Time", "Partial Upfront": "Monthly", "No Upfront": "Monthly"}},
+    {"target": "ContractCommitmentLifecycleStatus", "source": "state",
+     "value_map": {"active": "Active", "payment-pending": "Pending", "payment-failed": "Pending",
+                   "queued": "Proposed", "queued-deleted": "Canceled", "retired": "Expired",
+                   "pending-return": "Active", "returned": "Canceled"}},
+    {"target": "ContractCommitmentCreated", "source": "start", "transform": "date_to_utc"},
+    {"target": "ContractCommitmentBenefitCategory", "const": "Discount"},
+    {"target": "ContractCommitmentModel", "const": "Continuous"},
+    {"target": "ContractCommitmentFulfillmentInterval", "const": "Hourly"}
+  ]
+}

focus_data_toolkit/supplement/adapters/azure_invoice.json

@@ -0,0 +1,25 @@
+{
+  "adapter": "azure-invoice",
+  "version": "1",
+  "target_kind": "invoice",
+  "provenance": {
+    "source": "Azure Billing — Invoices REST API (Invoice resource)",
+    "doc_url": "https://learn.microsoft.com/en-us/rest/api/billing/invoices/get?view=rest-billing-2024-04-01",
+    "field_names_from": "Azure Billing REST API 2024-04-01 Invoice.properties; InvoiceStatus enum Due/OverDue/Paid/Void",
+    "retrieved": "2026-07-17",
+    "notes": "Flatten the invoice JSON so 'properties.*' become dot-path columns; the invoice number is the resource 'name'. Azure InvoiceStatus is a payment status (Due/OverDue/Paid) — all issued — mapped to FOCUS InvoiceIssueStatus 'Issued', with 'Void' -> 'Voided'. Azure MCA/EA invoices are issued by Microsoft, so InvoiceIssuerName is the constant 'Microsoft'; if a client's FOCUS source uses a different issuer string the join simply does not match (orphan/coverage diagnostics make that visible — never a silent wrong value). PaymentTerms is not exposed on the invoice resource and is left for the client."
+  },
+  "detect": {
+    "all_of": ["name", "properties.status", "properties.invoiceDate"],
+    "any_of": ["properties.dueDate", "properties.invoicePeriodStartDate", "properties.billingProfileDisplayName", "properties.invoiceType"]
+  },
+  "fields": [
+    {"target": "InvoiceId", "source": "name"},
+    {"target": "InvoiceIssuerName", "const": "Microsoft"},
+    {"target": "InvoiceIssueDate", "source": "properties.invoiceDate", "transform": "date_to_utc"},
+    {"target": "PaymentDueDate", "source": "properties.dueDate", "transform": "date_to_utc"},
+    {"target": "PurchaseOrderNumber", "source": "properties.purchaseOrderNumber"},
+    {"target": "InvoiceIssueStatus", "source": "properties.status",
+     "value_map": {"Due": "Issued", "OverDue": "Issued", "Paid": "Issued", "Void": "Voided"}}
+  ]
+}

focus_data_toolkit/supplement/adapters/gcp_compute_commitments.json

@@ -0,0 +1,28 @@
+{
+  "adapter": "gcp-compute-commitments",
+  "version": "1",
+  "target_kind": "contract_commitment",
+  "provenance": {
+    "source": "Google Compute Engine — regionCommitments (Commitment resource)",
+    "doc_url": "https://docs.cloud.google.com/compute/docs/reference/rest/v1/regionCommitments",
+    "field_names_from": "Compute Engine v1 Commitment resource: name, plan (TWELVE_MONTH/THIRTY_SIX_MONTH), status (CREATING/NOT_YET_ACTIVE/ACTIVE/EXPIRED/CANCELLED), startTimestamp, endTimestamp",
+    "retrieved": "2026-07-17",
+    "notes": "Shape of 'gcloud compute commitments list --format=json'. The three constants are invariant facts of GCP committed use discounts: they discount usage (BenefitCategory=Discount), apply continuously to eligible usage (Model=Continuous), and commit to an hourly rate (FulfillmentInterval=Hourly). GCP CUDs are billed monthly with no upfront payment, so PaymentModel=No Upfront and PaymentInterval=Monthly. ContractCommitmentLastUpdated and ContractCommitmentApplicability are NOT emitted (not present in the export) — the client supplies them and coverage reporting shows the residual gap. OfferCategory is left out (a commitment may be public or under a negotiated agreement, which the export does not distinguish)."
+  },
+  "detect": {
+    "all_of": ["name", "plan", "startTimestamp"],
+    "any_of": ["endTimestamp", "status", "region"]
+  },
+  "fields": [
+    {"target": "ContractCommitmentId", "source": "name"},
+    {"target": "ContractCommitmentCreated", "source": "startTimestamp", "transform": "date_to_utc"},
+    {"target": "ContractCommitmentLifecycleStatus", "source": "status",
+     "value_map": {"ACTIVE": "Active", "EXPIRED": "Expired", "NOT_YET_ACTIVE": "Proposed",
+                   "CREATING": "Pending", "CANCELLED": "Canceled", "CANCELED": "Canceled"}},
+    {"target": "ContractCommitmentPaymentModel", "const": "No Upfront"},
+    {"target": "ContractCommitmentPaymentInterval", "const": "Monthly"},
+    {"target": "ContractCommitmentBenefitCategory", "const": "Discount"},
+    {"target": "ContractCommitmentModel", "const": "Continuous"},
+    {"target": "ContractCommitmentFulfillmentInterval", "const": "Hourly"}
+  ]
+}

focus_data_toolkit/supplement/adapters/registry.py

@@ -0,0 +1,215 @@
+"""Provider-native supplement adapters — translate documented cloud export formats.
+
+The primary client journey is a cloud-provider customer holding FOCUS 1.2/1.3 **plus
+native provider artifacts** (invoice exports, reservation/commitment inventories) from
+AWS, Azure or GCP — not hand-authored FOCUS-named files. An **adapter** recognizes such a
+format by its native field names and translates each row into a canonical supplement kind
+(see :mod:`focus_data_toolkit.supplement.kinds`). The translated rows then flow through the
+*unchanged* supplement validation — adapters never bypass it.
+
+An adapter is **data, not code**: a vendored JSON mapping table (``adapters/*.json``) with a
+provenance block (official-doc URL, the model artifact the field names came from, retrieval
+date). The mapping only ever claims fields the vendored table describes; a value it cannot
+determine is simply not emitted (the client supplies it, and coverage reporting shows the
+residual gap). A file matching no adapter falls back to the generic FOCUS-named path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import lru_cache
+from pathlib import Path
+
+from focus_data_toolkit.supplement.kinds import SUPPLEMENT_KINDS
+from focus_data_toolkit.supplement.spec import SupplementError
+
+ADAPTERS_DIR = Path(__file__).resolve().parent
+PROVENANCE_FILENAME = "adapters_provenance.json"
+
+# FOCUS Date/Time: YYYY-MM-DDTHH:mm:ss[.fff]Z (UTC). We normalize provider timestamps to it.
+_DATE_ONLY = re.compile(r"\d{4}-\d{2}-\d{2}$")
+
+
+class AdapterError(SupplementError):
+    """An adapter mapping table is malformed or produces an invalid row."""
+
+
+def _to_utc_datetime(value: str) -> str:
+    """Normalize a provider timestamp to the FOCUS UTC form; pass through if unparseable.
+
+    An unparseable value is returned unchanged so the supplement validator flags it with a
+    precise diagnostic rather than the adapter silently dropping or guessing it.
+    """
+    text = value.strip()
+    if not text:
+        return ""
+    if _DATE_ONLY.fullmatch(text):
+        return f"{text}T00:00:00Z"
+    candidate = text.replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(candidate)
+    except ValueError:
+        return text
+    # Emit UTC 'Z'. Aware -> convert to UTC; naive -> assume already UTC.
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(UTC).replace(tzinfo=None)
+    micro = f".{dt.microsecond:06d}".rstrip("0") if dt.microsecond else ""
+    return dt.strftime("%Y-%m-%dT%H:%M:%S") + micro + "Z"
+
+
+_TRANSFORMS = {
+    "date_to_utc": _to_utc_datetime,
+}
+
+
+@dataclass(frozen=True)
+class FieldMapping:
+    """How one FOCUS target column is produced from the native row."""
+
+    target: str
+    source: str | None = None  # native field name (dot-path for nested JSON)
+    const: str | None = None  # fixed value (an invariant fact of the product type)
+    value_map: Mapping[str, str] | None = None  # native value -> FOCUS value
+    default: str | None = None  # value_map fallback (None = drop when unmapped)
+    transform: str | None = None  # a name in _TRANSFORMS applied to the source value
+
+    def produce(self, row: Mapping[str, str]) -> str | None:
+        if self.const is not None:
+            return self.const
+        assert self.source is not None
+        raw = (row.get(self.source) or "").strip()
+        if self.value_map is not None:
+            if not raw:
+                return None
+            mapped = self.value_map.get(raw, self.default)
+            return mapped  # None -> unmapped, drop (client supplies / coverage gap)
+        if self.transform:
+            raw = _TRANSFORMS[self.transform](raw)
+        return raw or None
+
+
+@dataclass(frozen=True)
+class Adapter:
+    """A vendored translation from one native provider export to a supplement kind."""
+
+    name: str
+    version: str
+    target_kind: str
+    detect_all_of: tuple[str, ...]
+    detect_any_of: tuple[str, ...]
+    fields: tuple[FieldMapping, ...]
+    provenance: Mapping[str, str]
+
+    def matches(self, header: Sequence[str]) -> bool:
+        present = set(header)
+        if not set(self.detect_all_of) <= present:
+            return False
+        return not self.detect_any_of or bool(present & set(self.detect_any_of))
+
+    def translate(self, rows: Sequence[Mapping[str, str]]) -> list[dict[str, str]]:
+        """Translate native rows into canonical-kind rows (FOCUS column names)."""
+        out: list[dict[str, str]] = []
+        for row in rows:
+            translated: dict[str, str] = {}
+            for field in self.fields:
+                value = field.produce(row)
+                if value is not None and value != "":
+                    translated[field.target] = value
+            out.append(translated)
+        return out
+
+    @property
+    def source_tag(self) -> str:
+        return f"{self.name}@{self.version}"
+
+
+def _parse_adapter(name: str, data: dict) -> Adapter:
+    try:
+        kind = data["target_kind"]
+        if kind not in SUPPLEMENT_KINDS:
+            raise AdapterError(f"adapter {name!r}: unknown target_kind {kind!r}")
+        fields = tuple(
+            FieldMapping(
+                target=f["target"],
+                source=f.get("source"),
+                const=f.get("const"),
+                value_map=f.get("value_map"),
+                default=f.get("default"),
+                transform=f.get("transform"),
+            )
+            for f in data["fields"]
+        )
+        adapter = Adapter(
+            name=data["adapter"],
+            version=str(data["version"]),
+            target_kind=kind,
+            detect_all_of=tuple(data["detect"].get("all_of", ())),
+            detect_any_of=tuple(data["detect"].get("any_of", ())),
+            fields=fields,
+            provenance=data.get("provenance", {}),
+        )
+    except (KeyError, TypeError) as exc:
+        raise AdapterError(f"adapter {name!r}: malformed mapping table ({exc})") from exc
+    # The adapter must produce its kind's join keys.
+    produced = {f.target for f in adapter.fields}
+    missing = [k for k in SUPPLEMENT_KINDS[kind].join_keys if k not in produced]
+    if missing:
+        raise AdapterError(
+            f"adapter {adapter.name!r} does not produce join key(s) {', '.join(missing)}"
+        )
+    # Every transform / target must be known.
+    for field in adapter.fields:
+        if field.transform and field.transform not in _TRANSFORMS:
+            raise AdapterError(
+                f"adapter {adapter.name!r}: unknown transform {field.transform!r}"
+            )
+    return adapter
+
+
+@lru_cache(maxsize=1)
+def load_adapters() -> dict[str, Adapter]:
+    """Load every vendored adapter mapping table (keyed by adapter name)."""
+    adapters: dict[str, Adapter] = {}
+    for path in sorted(ADAPTERS_DIR.glob("*.json")):
+        if path.name == PROVENANCE_FILENAME:
+            continue
+        data = json.loads(path.read_text(encoding="utf-8"))
+        adapter = _parse_adapter(path.stem, data)
+        adapters[adapter.name] = adapter
+    return adapters
+
+
+def get_adapter(name: str) -> Adapter:
+    adapter = load_adapters().get(name)
+    if adapter is None:
+        known = ", ".join(sorted(load_adapters())) or "(none)"
+        raise AdapterError(f"unknown adapter {name!r}; known adapters: {known}")
+    return adapter
+
+
+def detect_adapter(header: Sequence[str]) -> Adapter | None:
+    """Return the single adapter matching ``header``; ambiguity raises, no match is ``None``."""
+    matches = [a for a in load_adapters().values() if a.matches(header)]
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        return None
+    names = ", ".join(sorted(a.name for a in matches))
+    raise AdapterError(
+        f"provider export header is ambiguous between adapters: {names}; "
+        "force one with FILE:<adapter-name>"
+    )
+
+
+def adapter_provenance() -> dict:
+    """The vendored adapter provenance manifest (source docs + hashes)."""
+    return json.loads((ADAPTERS_DIR / PROVENANCE_FILENAME).read_text(encoding="utf-8"))
+
+
+def sha256_of(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()