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

focus_data_toolkit/errors.py

@@ -0,0 +1,145 @@
+"""Structured, client-actionable diagnostics.
+
+A :class:`Diagnostic` carries everything a user needs to locate and fix a problem in real
+client data: the stable rule code, severity, a human message, the business key of the
+offending record(s), and — where known — the file, dataset, physical line, column, value,
+expected/actual, a fix suggestion, provenance, and the group/join context. It renders to
+both JSON (for machine consumption) and a readable console block, and never degrades to
+``"invalid input"``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Severity(StrEnum):
+    ERROR = "ERROR"            # a real conformance/integrity violation
+    WARNING = "WARNING"        # suspicious, not necessarily invalid
+    INFO = "INFO"              # informational
+    NOT_EXECUTABLE = "NOT_EXECUTABLE"  # the check could not run (required data absent)
+    NOT_APPLICABLE = "NOT_APPLICABLE"  # the check does not apply to this bundle
+
+
+# Severities that represent an actual failure (used to compute a report's ``ok``).
+FAILING_SEVERITIES: frozenset[Severity] = frozenset({Severity.ERROR})
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One finding, addressable to a specific record / column / rule."""
+
+    code: str
+    severity: Severity
+    message: str
+    datasets: tuple[str, ...] = ()
+    file: str | None = None
+    dataset: str | None = None
+    line_number: int | None = None
+    record_keys: dict[str, str] = field(default_factory=dict)
+    column: str | None = None
+    value: str | None = None
+    expected: str | None = None
+    actual: str | None = None
+    rule: str | None = None
+    suggestion: str | None = None
+    provenance: str | None = None
+    source: str | None = None
+    context: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def is_failure(self) -> bool:
+        return self.severity in FAILING_SEVERITIES
+
+    def as_dict(self) -> dict:
+        """JSON-serialisable view (omitting empty fields)."""
+        out: dict = {
+            "rule_id": self.code,
+            "severity": self.severity.value,
+            "message": self.message,
+        }
+        if self.datasets:
+            out["datasets"] = list(self.datasets)
+        if self.dataset:
+            out["dataset"] = self.dataset
+        if self.file:
+            out["file"] = self.file
+        if self.line_number is not None:
+            out["line_number"] = self.line_number
+        if self.record_keys:
+            out["record_keys"] = dict(self.record_keys)
+        if self.column:
+            out["column"] = self.column
+        if self.value is not None:
+            out["value"] = self.value
+        if self.expected is not None:
+            out["expected"] = self.expected
+        if self.actual is not None:
+            out["actual"] = self.actual
+        if self.rule:
+            out["rule"] = self.rule
+        if self.suggestion:
+            out["suggestion"] = self.suggestion
+        if self.provenance:
+            out["provenance"] = self.provenance
+        if self.source:
+            out["source"] = self.source
+        if self.context:
+            out["context"] = dict(self.context)
+        return out
+
+    def as_row(self) -> dict[str, str]:
+        """Flat string row for CSV export of large violation sets."""
+        return {
+            "rule_id": self.code,
+            "severity": self.severity.value,
+            "datasets": ",".join(self.datasets),
+            "dataset": self.dataset or "",
+            "file": self.file or "",
+            "line_number": "" if self.line_number is None else str(self.line_number),
+            "record_keys": ";".join(f"{k}={v}" for k, v in self.record_keys.items()),
+            "column": self.column or "",
+            "value": "" if self.value is None else self.value,
+            "expected": "" if self.expected is None else self.expected,
+            "actual": "" if self.actual is None else self.actual,
+            "message": self.message,
+        }
+
+    def format(self) -> str:
+        """Readable multi-line console rendering (see module docstring example)."""
+        lines = [f"{self.severity.value} {self.code}: {self.message}"]
+        loc = []
+        if self.file:
+            loc.append(f"file={self.file}")
+        if self.dataset:
+            loc.append(f"dataset={self.dataset}")
+        if self.line_number is not None:
+            loc.append(f"row {self.line_number}")
+        if self.column:
+            loc.append(f"column={self.column}")
+        if loc:
+            lines.append("  " + " ".join(loc))
+        for key, val in self.record_keys.items():
+            lines.append(f'  {key}="{val}"')
+        if self.expected is not None or self.actual is not None:
+            lines.append(f"  expected={self.expected!r} actual={self.actual!r}")
+        if self.suggestion:
+            lines.append(f"  suggestion: {self.suggestion}")
+        return "\n".join(lines)
+
+
+CSV_FIELDNAMES: tuple[str, ...] = (
+    "rule_id",
+    "severity",
+    "datasets",
+    "dataset",
+    "file",
+    "line_number",
+    "record_keys",
+    "column",
+    "value",
+    "expected",
+    "actual",
+    "message",
+)

focus_data_toolkit/focus_json.py

@@ -0,0 +1,68 @@
+"""Deterministic JSON serialization for FOCUS JSON-typed columns.
+
+FOCUS types several JSON object properties as ``Numeric`` / ``Decimal`` (e.g.
+``AllocatedMethodDetails.AllocatedRatio``, ``ContractApplied.*AppliedCost``).
+Those MUST be serialized as JSON **numbers**, not quoted strings. To keep exact
+decimals (no float rounding) and byte-reproducible output, numeric properties are
+emitted by inserting their exact decimal text as a raw JSON number token rather
+than round-tripping through ``float``.
+
+:class:`JsonNumber` tags text that originated from a real JSON number token (use it
+as ``json.loads``'s ``parse_float``/``parse_int`` hook). It lets a parser tell a
+JSON number apart from a quoted numeric string after parsing, and lets ``_encode``
+re-emit such values as raw number literals (preserving custom numeric properties
+across a parse/serialize round-trip).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# JSON number grammar restricted to the FOCUS NumericFormat shape: no leading zeros,
+# E-notation with a negative-only exponent sign, no leading '+'.
+_JSON_NUMBER_RE = re.compile(r"-?(?:0|[1-9]\d*)(?:\.\d+)?(?:E-?\d+)?")
+
+
+class JsonNumber(str):
+    """Exact text of a value parsed from a JSON **number** token (not a string)."""
+
+    __slots__ = ()
+
+
+def is_json_number_literal(text: str) -> bool:
+    """True if ``text`` is a JSON number literal (FOCUS numeric shape)."""
+    return bool(_JSON_NUMBER_RE.fullmatch(text))
+
+
+def _raw_number(text: str, key: str | None = None) -> str:
+    if not is_json_number_literal(text):
+        where = f"property {key!r}" if key else "value"
+        raise ValueError(f"numeric {where} is not a JSON number: {text!r}")
+    return text
+
+
+def _encode(value: object, numeric_keys: frozenset[str]) -> str:
+    if isinstance(value, dict):
+        parts = []
+        for key, val in value.items():
+            if key in numeric_keys and isinstance(val, str):
+                parts.append(f"{json.dumps(key)}:{_raw_number(val, key)}")
+            else:
+                parts.append(f"{json.dumps(key)}:{_encode(val, numeric_keys)}")
+        return "{" + ",".join(parts) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(_encode(v, numeric_keys) for v in value) + "]"
+    if isinstance(value, JsonNumber):
+        return _raw_number(value)
+    return json.dumps(value)
+
+
+def dumps_object(obj: dict, *, numeric_keys: frozenset[str] = frozenset()) -> str:
+    """Serialize ``obj`` to compact JSON, emitting ``numeric_keys`` as JSON numbers.
+
+    ``numeric_keys`` applies by key name at any nesting depth, so numeric
+    properties inside an ``Elements`` array are emitted unquoted too. Values
+    tagged :class:`JsonNumber` are emitted as raw number literals regardless of key.
+    """
+    return _encode(obj, numeric_keys)

focus_data_toolkit/generators/__init__.py

@@ -0,0 +1,61 @@
+"""Deterministic, provider-realistic FOCUS 1.2/1.3 source generators.
+
+Each ``generate_<provider>_focus_<version>`` module is a thin shim binding a provider profile
+to a version adapter (see :mod:`focus_data_toolkit.generators.engine`); a given ``(rows, seed)``
+pair always produces the same CSV. All modules expose ``generate_csv_bytes(rows, seed)``; the
+1.3 modules additionally expose ``generate_contract_commitment_csv_bytes(rows, seed)``.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType, SimpleNamespace
+
+PROVIDERS: tuple[str, ...] = ("aws", "azure", "gcp")
+FOCUS_VERSIONS: tuple[str, ...] = ("1.2", "1.3")
+
+# In-process registry consulted first by get_generator. Lets tests register an extra provider
+# profile (a "fake" cloud) without adding a module file, proving the engine is provider-agnostic.
+_REGISTRY: dict[tuple[str, str], ModuleType | SimpleNamespace] = {}
+
+
+def register_generator(provider: str, focus_version: str, api: ModuleType | SimpleNamespace) -> None:
+    """Register an in-process generator (e.g. from ``engine._shim.build_module_api``).
+
+    ``api`` must expose ``generate_csv_bytes`` (and, for a 1.3-style adapter,
+    ``generate_contract_commitment_csv_bytes``). Test-oriented seam; production code uses the
+    six shipped modules via :func:`get_generator`.
+    """
+    _REGISTRY[(provider, focus_version)] = api
+
+
+def unregister_generator(provider: str, focus_version: str) -> None:
+    """Remove a previously registered in-process generator (no-op if absent)."""
+    _REGISTRY.pop((provider, focus_version), None)
+
+
+def get_generator(provider: str, focus_version: str) -> ModuleType | SimpleNamespace:
+    """Return the generator for ``provider`` and ``focus_version``.
+
+    Registered in-process generators win over the shipped modules; otherwise the matching
+    ``generate_<provider>_focus_<version>`` shim module is imported.
+    """
+    if (provider, focus_version) in _REGISTRY:
+        return _REGISTRY[(provider, focus_version)]
+    if provider not in PROVIDERS:
+        raise ValueError(f"unknown provider {provider!r}; expected one of {PROVIDERS}")
+    if focus_version not in FOCUS_VERSIONS:
+        raise ValueError(
+            f"unsupported FOCUS version {focus_version!r}; expected one of {FOCUS_VERSIONS}"
+        )
+    suffix = focus_version.replace(".", "_")
+    return import_module(f"focus_data_toolkit.generators.generate_{provider}_focus_{suffix}")
+
+
+__all__ = [
+    "FOCUS_VERSIONS",
+    "PROVIDERS",
+    "get_generator",
+    "register_generator",
+    "unregister_generator",
+]

focus_data_toolkit/generators/_shim.py

@@ -0,0 +1,43 @@
+"""Bind a (ProviderProfile, VersionAdapter) pair to the historical per-module public API.
+
+Each ``generate_<provider>_focus_<version>.py`` module is a ~10-line shim that calls
+:func:`build_module_api` and publishes the result, so ``COLUMNS`` / ``generate_csv_bytes`` /
+``generate_rows`` / ``main`` / the ``python -m`` entry point keep working unchanged.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any
+
+from focus_data_toolkit.generators.engine import serialize
+from focus_data_toolkit.generators.engine.ladder import generate_rows
+from focus_data_toolkit.generators.providers.profile import ProviderProfile
+from focus_data_toolkit.generators.versions.adapter import VersionAdapter
+
+
+def build_module_api(profile: ProviderProfile, adapter: VersionAdapter) -> dict[str, Any]:
+    """Return the names a generator shim module must expose, bound to (profile, adapter).
+
+    ``Any``-valued on purpose: the entries are heterogeneous module attributes (tuples,
+    callables, profile objects) that shim modules publish verbatim via ``globals().update``.
+    """
+    api: dict[str, Any] = {
+        "COLUMNS": adapter.columns,
+        "DEFAULT_ROWS": serialize.DEFAULT_ROWS,
+        "DEFAULT_SEED": adapter.default_seed,
+        "PROFILE": profile,
+        "ADAPTER": adapter,
+        "generate_rows": partial(generate_rows, profile=profile, adapter=adapter),
+        "generate_csv_bytes": partial(serialize.generate_csv_bytes, profile=profile, adapter=adapter),
+        "main": partial(serialize.main, profile=profile, adapter=adapter),
+    }
+    if adapter.contract_commitment_columns is not None:
+        api["CONTRACT_COMMITMENT_COLUMNS"] = adapter.contract_commitment_columns
+        api["generate_contract_commitment_rows"] = partial(
+            serialize.generate_contract_commitment_rows, profile=profile, adapter=adapter
+        )
+        api["generate_contract_commitment_csv_bytes"] = partial(
+            serialize.generate_contract_commitment_csv_bytes, profile=profile, adapter=adapter
+        )
+    return api

focus_data_toolkit/generators/engine/__init__.py

@@ -0,0 +1,14 @@
+"""Provider- and version-agnostic generation engine.
+
+The six ``generate_<provider>_focus_<version>`` modules are thin shims that bind a
+:class:`~focus_data_toolkit.generators.providers.profile.ProviderProfile` to a
+:class:`~focus_data_toolkit.generators.versions.adapter.VersionAdapter` and expose the
+public ``generate_csv_bytes`` / ``generate_rows`` / ``main`` API. All shared logic —
+determinism helpers, the FOCUS JSON builders, the row scenarios, the scenario ladder and
+CSV serialization — lives here, defined exactly once.
+
+Determinism contract: output is a pure function of the ordered sequence of RNG method
+calls. The engine preserves the historical call order per scenario, and each provider
+callable owns its own draw count, so a given ``(provider, focus_version, rows, seed)``
+reproduces the same bytes as before the refactor.
+"""

focus_data_toolkit/generators/engine/context.py

@@ -0,0 +1,12 @@
+"""Small value objects threaded through the engine row builders.
+
+``ResourceRef`` / ``RowContext`` live in :mod:`focus_data_toolkit.generators.providers.profile`
+next to the :class:`ServiceSpec` they reference, so the import graph stays a one-way street
+(engine -> providers) with no cycle. Re-exported here for the engine-side importers.
+"""
+
+from __future__ import annotations
+
+from focus_data_toolkit.generators.providers.profile import ResourceRef, RowContext
+
+__all__ = ["ResourceRef", "RowContext"]

focus_data_toolkit/generators/engine/determinism.py

@@ -0,0 +1,117 @@
+"""Shared deterministic helpers and constants for the generators.
+
+Every value here is identical across all providers and FOCUS versions (verified against
+the six historical generator modules). Rounding rules (``ROUND_HALF_UP`` + the quanta) and
+the billing window live in exactly one place so they can never drift between providers.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+from datetime import UTC, datetime, timedelta
+from decimal import ROUND_HALF_UP, Decimal
+
+# --------------------------------------------------------------------------- #
+# Billing window (fixed timestamps -> no clock -> byte-reproducible)
+# --------------------------------------------------------------------------- #
+BILLING_START = datetime(2026, 5, 1, tzinfo=UTC)
+BILLING_END = datetime(2026, 6, 1, tzinfo=UTC)
+PERIOD_DAYS = 28
+PERIOD_HOURS = PERIOD_DAYS * 24
+COMMIT_TERM_DAYS = 365  # 1-year commitment / contract term
+
+# --------------------------------------------------------------------------- #
+# Rounding quanta and commercial rates (single source of truth)
+# --------------------------------------------------------------------------- #
+COST_Q = Decimal("0.000001")
+PRICE_Q = Decimal("0.0000000001")
+QTY_Q = Decimal("0.0001")
+EUR_PER_USD = Decimal("0.92")
+COMMIT_RATE = Decimal("0.667")  # amortised commitment rate vs on-demand list
+PRIVATE_RATE = Decimal("0.90")  # negotiated (contracted) rate vs list for on-demand
+COMMIT_TERM_HOURS = Decimal("8760")  # 1-year reservation term
+
+# --------------------------------------------------------------------------- #
+# Shared value pools and FOCUS vocabularies
+# --------------------------------------------------------------------------- #
+ENVIRONMENTS = ("prod", "staging", "dev")
+COST_CENTERS = ("cc-1042", "cc-2087", "cc-3110")
+OWNERS = ("team-platform", "team-data", "team-payments")
+
+PRICING_CATEGORIES: tuple[str, ...] = ("Standard", "Dynamic", "Committed", "Other")
+# FOCUS-defined SkuPriceDetails property keys (others MUST be x_-prefixed).
+FOCUS_SKU_PRICE_KEYS: frozenset[str] = frozenset(
+    {
+        "CoreCount",
+        "MemorySize",
+        "InstanceType",
+        "InstanceSeries",
+        "OperatingSystem",
+        "DiskType",
+        "DiskSpace",
+        "DiskMaxIops",
+        "GpuCount",
+        "NetworkMaxIops",
+        "NetworkMaxThroughput",
+    }
+)
+
+HEX_LOWER = "0123456789abcdef"
+HEX_UPPER = "0123456789ABCDEF"
+
+
+def q(value: Decimal, quant: Decimal) -> Decimal:
+    """Quantise ``value`` to ``quant`` using banker-free ROUND_HALF_UP (FOCUS rounding)."""
+    return value.quantize(quant, rounding=ROUND_HALF_UP)
+
+
+def s(value: Decimal) -> str:
+    """Render a Decimal as fixed-point text (never scientific notation)."""
+    return format(value, "f")
+
+
+def iso(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_iso(value: str) -> datetime:
+    return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=UTC)
+
+
+def hexid(rng: random.Random, width: int, alphabet: str = HEX_LOWER) -> str:
+    """Draw ``width`` characters from ``alphabet`` (default lowercase hex)."""
+    return "".join(rng.choice(alphabet) for _ in range(width))
+
+
+def period(i: int, granularity: str) -> tuple[str, str]:
+    if granularity == "hourly":
+        start = BILLING_START + timedelta(hours=i % PERIOD_HOURS)
+        return iso(start), iso(start + timedelta(hours=1))
+    if granularity == "daily":
+        start = BILLING_START + timedelta(days=i % PERIOD_DAYS)
+        return iso(start), iso(start + timedelta(days=1))
+    return iso(BILLING_START), iso(BILLING_END)
+
+
+def sku_price_details(spec_sku_details: dict[str, object]) -> str:
+    return json.dumps(spec_sku_details, separators=(",", ":"))
+
+
+def contract_id_for(commit_id: str) -> str:
+    """Deterministic parent ContractId for a commitment id (shared by both 1.3 datasets)."""
+    return f"CONTRACT-{commit_id.rsplit('/', 1)[-1][:12]}"
+
+
+def set_currency(
+    row: dict[str, str],
+    pricing_currency: str,
+    list_unit: Decimal,
+    contracted_unit: Decimal,
+    effective_cost: Decimal,
+) -> None:
+    row["PricingCurrency"] = pricing_currency
+    fx = EUR_PER_USD if pricing_currency == "EUR" else Decimal("1")
+    row["PricingCurrencyListUnitPrice"] = s(q(list_unit * fx, PRICE_Q))
+    row["PricingCurrencyContractedUnitPrice"] = s(q(contracted_unit * fx, PRICE_Q))
+    row["PricingCurrencyEffectiveCost"] = s(q(effective_cost * fx, COST_Q))

focus_data_toolkit/generators/engine/json_focus.py

@@ -0,0 +1,63 @@
+"""Single-source FOCUS JSON builders for the generators.
+
+Both the Split Cost Allocation ``AllocatedMethodDetails`` object and the
+``ContractApplied`` object are FOCUS JSON with *Numeric* properties that MUST be emitted
+as JSON numbers (not quoted strings). They are built here, once, on top of
+:func:`focus_data_toolkit.focus_json.dumps_object`, so no generator, provider or scenario
+re-implements the rule. Previously the SCA object was built two divergent ways (the 1.3
+generators via ``dumps_object``; ``scenarios.py`` by string concatenation) — both now route
+through :func:`allocated_method_details`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from focus_data_toolkit.focus_json import dumps_object
+
+# AllocatedMethodDetails.Elements[*] numeric properties (FOCUS 1.3 Split Cost Allocation).
+SCA_NUMERIC_KEYS: frozenset[str] = frozenset({"AllocatedRatio", "UsageQuantity"})
+# ContractApplied.Elements[*] numeric properties (FOCUS 1.3).
+CONTRACT_APPLIED_NUMERIC_KEYS: frozenset[str] = frozenset(
+    {"ContractCommitmentAppliedCost", "ContractCommitmentAppliedQuantity"}
+)
+
+
+def allocated_method_details(
+    elements: Sequence[Mapping[str, object]],
+    *,
+    numeric_keys: frozenset[str] = SCA_NUMERIC_KEYS,
+) -> str:
+    """Serialise a FOCUS ``AllocatedMethodDetails`` object from its ``Elements``.
+
+    Each element's numeric properties (``AllocatedRatio`` / ``UsageQuantity`` by default)
+    are emitted as JSON numbers; their string values must be JSON number literals or
+    ``dumps_object`` raises (a stricter, safer contract than string concatenation).
+    """
+    return dumps_object({"Elements": list(elements)}, numeric_keys=numeric_keys)
+
+
+def contract_applied(
+    commit_id: str,
+    contract_id: str,
+    applied_cost: str,
+    applied_qty: str,
+    applied_unit: str,
+) -> str:
+    """FOCUS 1.3 ``ContractApplied`` JSON: a top-level ``Elements`` array linking a Cost
+    and Usage row to the Contract Commitment dataset via ``ContractCommitmentID``. The
+    applied cost/quantity are emitted as JSON numbers."""
+    return dumps_object(
+        {
+            "Elements": [
+                {
+                    "ContractID": contract_id,
+                    "ContractCommitmentID": commit_id,
+                    "ContractCommitmentAppliedCost": applied_cost,
+                    "ContractCommitmentAppliedQuantity": applied_qty,
+                    "ContractCommitmentAppliedUnit": applied_unit,
+                }
+            ]
+        },
+        numeric_keys=CONTRACT_APPLIED_NUMERIC_KEYS,
+    )

focus_data_toolkit/generators/engine/ladder.py

@@ -0,0 +1,71 @@
+"""The scenario-selection loop shared by every generator.
+
+Draws exactly one ``rng.random()`` per output position (as the historical generators did) and
+dispatches to a scenario builder via the version adapter's ladder, preserving the original
+``if/elif`` semantics precisely.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+
+from focus_data_toolkit.generators.engine import scenarios_core
+
+DEFAULT_ROWS = 1000
+
+# A builder returns either one row or a whole group of rows; the branch's ``group`` flag
+# (mirrored in the isinstance checks below) says which, so the union is narrowed per call.
+_Builder = Callable[..., "dict[str, str] | list[dict[str, str]]"]
+
+_BUILDERS: dict[str, _Builder] = {
+    "credit": scenarios_core.credit_row,
+    "tax": scenarios_core.tax_row,
+    "purchase": scenarios_core.standalone_purchase_row,
+    "split": scenarios_core.split_allocation_row,
+    "commitment": scenarios_core.commitment_group,
+}
+
+
+def generate_rows(
+    rows: int = DEFAULT_ROWS,
+    seed: int | None = None,
+    *,
+    include_credits: bool = False,
+    profile,
+    adapter,
+) -> list[dict[str, str]]:
+    """Return ``rows`` synthetic records for ``profile``/``adapter`` as ordered string dicts.
+
+    ``rows``/``seed`` default to the historical per-module values (1000 rows; the adapter's
+    default seed) so the shim ``generate_rows()`` / ``generate_rows(rows=N)`` calls keep working.
+    """
+    if seed is None:
+        seed = adapter.default_seed
+    if rows < 1:
+        raise ValueError("rows must be >= 1")
+    rng = random.Random(seed)
+    out: list[dict[str, str]] = []
+    while len(out) < rows:
+        i = len(out)
+        remaining = rows - i
+        roll = rng.random()
+        chosen = None
+        for branch in adapter.ladder:
+            if branch.requires_credits and not include_credits:
+                continue
+            if roll < branch.threshold:
+                if branch.min_remaining is None or remaining >= branch.min_remaining:
+                    chosen = branch
+                break  # first threshold match wins (elif semantics); guard failure -> Usage
+        if chosen is None:
+            out.append(scenarios_core.usage_row(rng, i, remaining, profile, adapter))
+            continue
+        built = _BUILDERS[chosen.kind](rng, i, remaining, profile, adapter)
+        if chosen.group:
+            assert isinstance(built, list), chosen.kind
+            out.extend(built)
+        else:
+            assert isinstance(built, dict), chosen.kind
+            out.append(built)
+    return out[:rows]