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

focus_data_toolkit/generators/providers/profile.py

@@ -0,0 +1,123 @@
+"""Dataclasses describing a cloud provider's synthetic-data profile.
+
+These hold only what is genuinely provider-specific. The engine reads the tables and calls
+the callables in a fixed order, so each callable owns its own RNG draw count (which is how
+per-provider byte output is reproduced despite differing id widths/alphabets and — for
+commitments — differing draw *order*).
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+
+@dataclass(frozen=True)
+class ServiceSpec:
+    """One synthetic service. ``id_fields`` carries provider-specific resource-id parts
+    (AWS ``arn_kind``; Azure ``arm_type``; GCP ``api``/``collection``) opaquely — only the
+    provider's ``resource_id`` callable reads them."""
+
+    name: str
+    category: str
+    subcategory: str
+    resource_type: str
+    sku_meter: str  # the SKU "Function" (Compute / Storage / Database / ...)
+    pricing_unit: str  # FOCUS UnitFormat
+    description: str
+    unit_price_usd: Decimal
+    qty_low: Decimal
+    qty_high: Decimal
+    name_prefix: str
+    granularity: str  # "hourly" | "daily" | "monthly"
+    zonal: bool
+    commitment_eligible: bool
+    id_fields: Mapping[str, object] = field(default_factory=dict)
+    sku_details: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RowContext:
+    """Identity carried from ``base_row`` into a scenario (the group's billing account)."""
+
+    billing_id: str
+    sub_id: str
+    sub_name: str
+
+
+@dataclass(frozen=True)
+class ResourceRef:
+    """Everything a provider's ``resource_id`` callable might need.
+
+    Each provider reads only the fields it uses (AWS: region + billing account; Azure:
+    subscription id + name; GCP: project id), so the callable signature stays uniform and
+    the callables never draw from the RNG.
+    """
+
+    spec: ServiceSpec
+    region_id: str
+    region_name: str
+    billing_id: str
+    sub_id: str
+    sub_name: str
+    resource_name: str
+
+
+@dataclass(frozen=True)
+class CommitmentModel:
+    """Provider-specific commitment terms and id/sku formats.
+
+    ``spend_based`` is drawn once by the engine (``rng.random() < 0.6``) and passed in, so
+    the callables never re-draw the spend/usage split. ``commit_id_before_base_row`` captures
+    the one real cross-provider *ordering* difference: AWS draws the commitment id (from the
+    region) before the purchase ``base_row``; Azure/GCP draw it after, from the subscription /
+    project id. The two RNG-drawing callables own their own hex widths.
+    """
+
+    commit_id_before_base_row: bool
+    commit_id: Callable[[random.Random, str, str, bool], str]  # (rng, region_id, sub_id, spend_based)
+    commit_resource_name: Callable[[random.Random, bool], str]  # (rng, spend_based)
+    purchase_sku_id: Callable[[random.Random], str]  # (rng) -> commitment purchase SkuId
+    purchase_sku_details: Callable[[bool], str]  # (spend_based) -> SkuPriceDetails JSON
+    purchase_description: Callable[[str], str]  # (commit_type) -> Purchase ChargeDescription
+    commit_name: Callable[[bool], str]
+    commit_type: Callable[[bool], str]  # ResourceType + CommitmentDiscountType
+    commit_category: Callable[[bool], str]  # "Spend" | "Usage"
+    commit_unit: Callable[[bool], str]  # "USD" | "Hours"
+
+
+@dataclass(frozen=True)
+class ProviderProfile:
+    key: str  # "aws" | "azure" | "gcp"
+    provider_name: str
+    publisher_name: str
+    service_provider_name: str  # FOCUS 1.3 identity (used only by the 1.3 adapter)
+    host_provider_name: str
+    invoice_issuer_name: str
+    billing_account_type: str
+    sub_account_type: str
+    split_allocation_description: str  # "Shared <service> host cost allocated to workload"
+    tag_keys: tuple[str, str, str]  # (environment, cost-center, owner) tag key names
+    invoice_id: Callable[[str], str]  # (billing_id) -> InvoiceId
+    services: tuple[ServiceSpec, ...]
+    regions: tuple[tuple[str, str, tuple[str, ...]], ...]
+    billing_accounts: tuple[tuple[str, str], ...]
+    sub_accounts: tuple[tuple[str, str], ...]
+    resource_id: Callable[[ResourceRef], str]  # pure, never draws
+    resource_name: Callable[[random.Random, ServiceSpec], str]  # usage/purchase resource name
+    committed_resource_name: Callable[[random.Random, ServiceSpec, int], str]  # committed-usage (index k)
+    sku_id: Callable[[random.Random, ServiceSpec], str]
+    sku_price_id: Callable[[random.Random], str]
+    allocated_resource_id: Callable[[random.Random, str, RowContext, str], str]  # (rng, region_id, ctx, workload)
+    commitment: CommitmentModel
+
+    @property
+    def commitment_service(self) -> ServiceSpec:
+        """The service used for commitment and split-allocation rows (services[0])."""
+        return self.services[0]
+
+    @property
+    def allowed_subcategories(self) -> frozenset[str]:
+        return frozenset(spec.subcategory for spec in self.services)

focus_data_toolkit/generators/scenarios.py

@@ -0,0 +1,178 @@
+"""Coherent, provider-agnostic FOCUS scenario generators (P1.8 / P1.9 / P1.10).
+
+Unlike the large per-provider generators (which emit whole Cost and Usage files), these build
+small, *self-consistent* scenarios that exercise the cross-dataset validators on realistic —
+not random — data:
+
+* :func:`split_allocation_group` — a Split Cost Allocation group whose ratios sum to exactly 1
+  and whose allocated costs sum to exactly the origin charge (the last consumer absorbs the
+  rounding residue), so it passes :func:`~focus_data_toolkit.validate.allocation.validate_split_allocation`.
+* :func:`correction_set` — an original charge plus a signed correction line
+  (``ChargeClass="Correction"``) that references it and records the auditable net charge.
+* :func:`billing_lifecycle_instances` — a T0→T6 sequence of
+  :class:`~focus_data_toolkit.lifecycle.DatasetInstance` snapshots (period opens, fills, closes;
+  invoice is issued, voided, replaced) with only *allowed* status transitions.
+
+Everything is deterministic (no RNG, no clock): the same arguments always yield the same rows,
+so the scenarios are byte-reproducible and safe to snapshot in tests.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from decimal import Decimal
+
+from focus_data_toolkit.generators.engine.json_focus import allocated_method_details
+from focus_data_toolkit.lifecycle import DatasetInstance
+
+_RATIO_QUANTUM = Decimal("0.000001")
+_COST_QUANTUM = Decimal("0.000001")
+
+
+def split_allocation_group(
+    origin_id: str,
+    origin_cost: str | Decimal,
+    weights: Sequence[float | int | str | Decimal],
+    *,
+    method: str = "split-proportional",
+    unit: str = "Hours",
+    resource_prefix: str = "res",
+) -> list[dict[str, str]]:
+    """Build a valid Split Cost Allocation group distributing ``origin_cost`` over ``weights``.
+
+    Ratios sum to exactly 1 and allocated ``BilledCost`` sums to exactly ``origin_cost``: each
+    consumer gets ``weight/total`` (quantised), and the **last** consumer takes the residue so
+    no cents are created or lost. ``weights`` may encode equal (all 1), proportional, or
+    weighted allocation, and may be negative for a correction that redistributes a credit.
+    """
+    if len(weights) < 1:
+        raise ValueError("an allocation group needs at least one consumer")
+    origin = Decimal(str(origin_cost))
+    decimal_weights = [Decimal(str(w)) for w in weights]
+    total = sum(decimal_weights, Decimal(0))
+    if total == 0:
+        raise ValueError("allocation weights sum to zero; cannot form ratios")
+
+    ratios: list[Decimal] = []
+    costs: list[Decimal] = []
+    acc_ratio = Decimal(0)
+    acc_cost = Decimal(0)
+    last = len(decimal_weights) - 1
+    for i, w in enumerate(decimal_weights):
+        if i < last:
+            ratio = (w / total).quantize(_RATIO_QUANTUM)
+            cost = (origin * w / total).quantize(_COST_QUANTUM)
+            acc_ratio += ratio
+            acc_cost += cost
+        else:  # last consumer absorbs the residue so both sums stay exact
+            ratio = Decimal(1) - acc_ratio
+            cost = origin - acc_cost
+        ratios.append(ratio)
+        costs.append(cost)
+
+    return [
+        {
+            "x_SplitOriginId": origin_id,
+            "x_SplitOriginCost": str(origin),
+            "AllocatedMethodId": method,
+            "AllocatedResourceId": f"{resource_prefix}-{i}",
+            "AllocatedMethodDetails": allocated_method_details(
+                [{"AllocatedRatio": str(ratios[i]), "UsageUnit": unit, "UsageQuantity": "1"}]
+            ),
+            "BilledCost": str(costs[i]),
+            "ChargeCategory": "Usage",
+        }
+        for i in range(len(decimal_weights))
+    ]
+
+
+def correction_set(
+    charge_key: str,
+    original_cost: str | Decimal,
+    corrections: Sequence[str | Decimal],
+    *,
+    invoice_id: str = "INV-1",
+    currency: str = "USD",
+    charge_category: str = "Usage",
+) -> list[dict[str, str]]:
+    """An original charge plus one signed correction line per entry in ``corrections``.
+
+    The original keeps its own ``x_ChargeKey`` (never overwritten); each correction is a
+    ``ChargeClass="Correction"`` line that references the original via ``x_CorrectionOf`` and
+    records the running auditable net (``x_NetCharge`` = original + corrections so far). The net
+    of the whole set is therefore verifiable and no history is destroyed.
+    """
+    original = Decimal(str(original_cost))
+    rows = [
+        {
+            "x_ChargeKey": charge_key,
+            "ChargeClass": "",
+            "ChargeCategory": charge_category,
+            "BilledCost": str(original),
+            "InvoiceId": invoice_id,
+            "BillingCurrency": currency,
+        }
+    ]
+    running = original
+    for n, amount in enumerate(corrections, start=1):
+        delta = Decimal(str(amount))
+        running += delta
+        rows.append(
+            {
+                "x_ChargeKey": f"{charge_key}-c{n}",
+                "x_CorrectionOf": charge_key,
+                "ChargeClass": "Correction",
+                "ChargeCategory": "Credit" if delta < 0 else charge_category,
+                "BilledCost": str(delta),
+                "x_NetCharge": str(running),
+                "InvoiceId": invoice_id,
+                "BillingCurrency": currency,
+            }
+        )
+    return rows
+
+
+def billing_lifecycle_instances(
+    *,
+    invoice_id: str = "INV-1",
+    period_start: str = "2026-01-01T00:00:00Z",
+    period_end: str = "2026-02-01T00:00:00Z",
+    replacement_invoice_id: str = "INV-1-R1",
+) -> list[DatasetInstance]:
+    """A canonical T0→T6 billing lifecycle as a sequence of dataset-instance snapshots.
+
+    T0 period opens (incomplete) → T1 more Cost and Usage arrives → T2 period closes → T3
+    invoice issued → T4 late correction recorded → T5 invoice voided → T6 replacement issued.
+    Only allowed status transitions occur; each snapshot links to the previous one.
+    """
+    steps = [
+        ("t0", "Billing Period", False, "Open", None),
+        ("t1", "Billing Period", False, "Open", "t0"),
+        ("t2", "Billing Period", True, "Closed", "t1"),
+        ("t3", "Invoice Detail", True, "Issued", "t2"),
+        ("t4", "Invoice Detail", True, "Issued", "t3"),  # correction recorded, still issued
+        ("t5", "Invoice Detail", True, "Voided", "t4"),
+        ("t6", "Invoice Detail", True, "Issued", "t5"),  # replacement invoice issued
+    ]
+    instances: list[DatasetInstance] = []
+    for order, (instance_id, dataset, complete, status, prev) in enumerate(steps):
+        inv = replacement_invoice_id if instance_id == "t6" else invoice_id
+        instances.append(
+            DatasetInstance(
+                instance_id=instance_id,
+                dataset=dataset,
+                subject_id=inv,
+                order=order,
+                created=period_start,
+                last_updated=period_end,
+                complete=complete,
+                period_start=period_start,
+                period_end=period_end,
+                status=status,
+                previous_instance_id=prev,
+            )
+        )
+    return instances
+
+
+__all__ = ["billing_lifecycle_instances", "correction_set", "split_allocation_group"]

focus_data_toolkit/generators/versions/__init__.py

@@ -0,0 +1,17 @@
+"""FOCUS version adapters (1.2, 1.3).
+
+An adapter owns everything that differs between FOCUS versions: the column set, the optional
+Contract Commitment dataset, the scenario ladder, and the small per-version field hooks
+(the 1.3 provider-identity split, ``PricingCurrencyEffectiveCost`` on Tax/Credit, and the
+``ContractApplied`` link). Providers are version-agnostic; adapters are provider-agnostic.
+"""
+
+from __future__ import annotations
+
+from focus_data_toolkit.generators.versions.adapter import LadderBranch, VersionAdapter
+from focus_data_toolkit.generators.versions.v1_2 import V12
+from focus_data_toolkit.generators.versions.v1_3 import V13
+
+ADAPTERS: dict[str, VersionAdapter] = {V12.version: V12, V13.version: V13}
+
+__all__ = ["ADAPTERS", "LadderBranch", "V12", "V13", "VersionAdapter"]

focus_data_toolkit/generators/versions/adapter.py

@@ -0,0 +1,41 @@
+"""The ``VersionAdapter`` strategy object and the scenario-ladder description."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from focus_data_toolkit.generators.providers.profile import ProviderProfile
+
+
+@dataclass(frozen=True)
+class LadderBranch:
+    """One branch of the scenario-selection ladder, evaluated in order.
+
+    Mirrors the historical ``if/elif`` chain exactly: the first branch whose threshold the
+    roll falls under is chosen (``requires_credits`` branches are skipped unless credits are
+    enabled); if that branch's ``min_remaining`` guard fails the row falls through to Usage.
+    """
+
+    kind: str  # "credit" | "tax" | "purchase" | "split" | "commitment"
+    threshold: float
+    requires_credits: bool = False
+    min_remaining: int | None = None
+    group: bool = False  # True if the builder returns multiple rows (commitment)
+
+
+@dataclass(frozen=True)
+class VersionAdapter:
+    version: str  # "1.2" | "1.3"
+    default_seed: int
+    columns: tuple[str, ...]
+    contract_commitment_columns: tuple[str, ...] | None
+    ladder: tuple[LadderBranch, ...]
+    # Keys copied verbatim from a commitment Purchase row onto every linked usage row.
+    commitment_identity_keys: tuple[str, ...]
+    emits_split_allocation: bool
+    # Per-version field hooks (no-ops in 1.2):
+    fill_version_identity: Callable[[dict, ProviderProfile], None]  # (row, profile)
+    on_tax_row: Callable[[dict, str], None]  # (row, amount_str)
+    on_credit_row: Callable[[dict, str], None]  # (row, negative_str)
+    on_commit_usage: Callable[[dict, str, str, str], None]  # (usage, commit_id, contract_id, effective_str)

focus_data_toolkit/generators/versions/v1_2.py

@@ -0,0 +1,111 @@
+"""FOCUS 1.2 adapter: 57-column Cost and Usage, no Contract Commitment dataset."""
+
+from __future__ import annotations
+
+from focus_data_toolkit.generators.versions.adapter import LadderBranch, VersionAdapter
+
+COLUMNS: tuple[str, ...] = (
+    "ProviderName",
+    "PublisherName",
+    "InvoiceIssuerName",
+    "InvoiceId",
+    "BillingAccountId",
+    "BillingAccountName",
+    "BillingAccountType",
+    "SubAccountId",
+    "SubAccountName",
+    "SubAccountType",
+    "BillingPeriodStart",
+    "BillingPeriodEnd",
+    "ChargePeriodStart",
+    "ChargePeriodEnd",
+    "ChargeCategory",
+    "ChargeClass",
+    "ChargeDescription",
+    "ChargeFrequency",
+    "BilledCost",
+    "EffectiveCost",
+    "ListCost",
+    "ContractedCost",
+    "ListUnitPrice",
+    "ContractedUnitPrice",
+    "PricingCategory",
+    "PricingQuantity",
+    "PricingUnit",
+    "PricingCurrency",
+    "PricingCurrencyContractedUnitPrice",
+    "PricingCurrencyEffectiveCost",
+    "PricingCurrencyListUnitPrice",
+    "BillingCurrency",
+    "ConsumedQuantity",
+    "ConsumedUnit",
+    "ServiceName",
+    "ServiceCategory",
+    "ServiceSubcategory",
+    "SkuId",
+    "SkuMeter",
+    "SkuPriceId",
+    "SkuPriceDetails",
+    "ResourceId",
+    "ResourceName",
+    "ResourceType",
+    "RegionId",
+    "RegionName",
+    "AvailabilityZone",
+    "CommitmentDiscountId",
+    "CommitmentDiscountName",
+    "CommitmentDiscountCategory",
+    "CommitmentDiscountType",
+    "CommitmentDiscountStatus",
+    "CommitmentDiscountQuantity",
+    "CommitmentDiscountUnit",
+    "CapacityReservationId",
+    "CapacityReservationStatus",
+    "Tags",
+)
+
+assert len(COLUMNS) == 57, f"FOCUS 1.2 must have 57 columns, got {len(COLUMNS)}"
+assert len(set(COLUMNS)) == 57, "FOCUS 1.2 column names must be unique"
+
+# In 1.2 the commitment usage rows copied only the account ids from the purchase.
+_COMMITMENT_IDENTITY_KEYS: tuple[str, ...] = (
+    "BillingAccountId",
+    "SubAccountId",
+    "SubAccountName",
+)
+
+
+def _noop_identity(row: dict, profile: object) -> None:
+    """1.2 has no ServiceProviderName/HostProviderName and does not seed PricingCurrency."""
+
+
+def _noop_tax(row: dict, amount_str: str) -> None:
+    """1.2 leaves PricingCurrencyEffectiveCost null on Tax."""
+
+
+def _noop_credit(row: dict, negative_str: str) -> None:
+    """1.2 leaves PricingCurrencyEffectiveCost null on Credit."""
+
+
+def _noop_commit_usage(usage: dict, commit_id: str, contract_id: str, effective_str: str) -> None:
+    """1.2 has no ContractApplied column."""
+
+
+V12 = VersionAdapter(
+    version="1.2",
+    default_seed=1202,
+    columns=COLUMNS,
+    contract_commitment_columns=None,
+    ladder=(
+        LadderBranch("credit", 0.05, requires_credits=True),
+        LadderBranch("tax", 0.12),
+        LadderBranch("purchase", 0.20),
+        LadderBranch("commitment", 0.45, min_remaining=6, group=True),
+    ),
+    commitment_identity_keys=_COMMITMENT_IDENTITY_KEYS,
+    emits_split_allocation=False,
+    fill_version_identity=_noop_identity,
+    on_tax_row=_noop_tax,
+    on_credit_row=_noop_credit,
+    on_commit_usage=_noop_commit_usage,
+)

focus_data_toolkit/generators/versions/v1_3.py

@@ -0,0 +1,154 @@
+"""FOCUS 1.3 adapter: 65-column Cost and Usage + 13-column Contract Commitment."""
+
+from __future__ import annotations
+
+from focus_data_toolkit.generators.engine.json_focus import contract_applied
+from focus_data_toolkit.generators.providers.profile import ProviderProfile
+from focus_data_toolkit.generators.versions.adapter import LadderBranch, VersionAdapter
+
+COLUMNS: tuple[str, ...] = (
+    "ProviderName",
+    "PublisherName",
+    "ServiceProviderName",
+    "HostProviderName",
+    "InvoiceIssuerName",
+    "InvoiceId",
+    "BillingAccountId",
+    "BillingAccountName",
+    "BillingAccountType",
+    "SubAccountId",
+    "SubAccountName",
+    "SubAccountType",
+    "BillingPeriodStart",
+    "BillingPeriodEnd",
+    "ChargePeriodStart",
+    "ChargePeriodEnd",
+    "ChargeCategory",
+    "ChargeClass",
+    "ChargeDescription",
+    "ChargeFrequency",
+    "BilledCost",
+    "EffectiveCost",
+    "ListCost",
+    "ContractedCost",
+    "ListUnitPrice",
+    "ContractedUnitPrice",
+    "PricingCategory",
+    "PricingQuantity",
+    "PricingUnit",
+    "PricingCurrency",
+    "PricingCurrencyContractedUnitPrice",
+    "PricingCurrencyEffectiveCost",
+    "PricingCurrencyListUnitPrice",
+    "BillingCurrency",
+    "ConsumedQuantity",
+    "ConsumedUnit",
+    "ServiceName",
+    "ServiceCategory",
+    "ServiceSubcategory",
+    "SkuId",
+    "SkuMeter",
+    "SkuPriceId",
+    "SkuPriceDetails",
+    "ResourceId",
+    "ResourceName",
+    "ResourceType",
+    "RegionId",
+    "RegionName",
+    "AvailabilityZone",
+    "CommitmentDiscountId",
+    "CommitmentDiscountName",
+    "CommitmentDiscountCategory",
+    "CommitmentDiscountType",
+    "CommitmentDiscountStatus",
+    "CommitmentDiscountQuantity",
+    "CommitmentDiscountUnit",
+    "ContractApplied",
+    "CapacityReservationId",
+    "CapacityReservationStatus",
+    "AllocatedMethodId",
+    "AllocatedMethodDetails",
+    "AllocatedResourceId",
+    "AllocatedResourceName",
+    "AllocatedTags",
+    "Tags",
+)
+
+assert len(COLUMNS) == 65, f"FOCUS 1.3 Cost and Usage must have 65 columns, got {len(COLUMNS)}"
+assert len(set(COLUMNS)) == 65, "FOCUS 1.3 Cost and Usage column names must be unique"
+
+CONTRACT_COMMITMENT_COLUMNS: tuple[str, ...] = (
+    "ContractCommitmentId",
+    "ContractCommitmentType",
+    "ContractCommitmentCategory",
+    "ContractCommitmentCost",
+    "ContractCommitmentQuantity",
+    "ContractCommitmentUnit",
+    "ContractCommitmentDescription",
+    "ContractCommitmentPeriodStart",
+    "ContractCommitmentPeriodEnd",
+    "ContractId",
+    "ContractPeriodStart",
+    "ContractPeriodEnd",
+    "BillingCurrency",
+)
+
+assert len(CONTRACT_COMMITMENT_COLUMNS) == 13, (
+    f"FOCUS 1.3 Contract Commitment must have 13 columns, got {len(CONTRACT_COMMITMENT_COLUMNS)}"
+)
+assert len(set(CONTRACT_COMMITMENT_COLUMNS)) == 13, (
+    "FOCUS 1.3 Contract Commitment column names must be unique"
+)
+
+# In 1.3 every linked usage row copies the full billing identity of the commitment.
+_COMMITMENT_IDENTITY_KEYS: tuple[str, ...] = (
+    "BillingAccountId",
+    "BillingAccountName",
+    "BillingAccountType",
+    "SubAccountId",
+    "SubAccountName",
+    "SubAccountType",
+    "InvoiceId",
+)
+
+
+def _fill_identity(row: dict, profile: ProviderProfile) -> None:
+    row["ServiceProviderName"] = profile.service_provider_name
+    row["HostProviderName"] = profile.host_provider_name
+    # Multi-currency generator: PricingCurrency is never null (_set_currency overrides it for
+    # priced rows; Tax/Credit keep this USD default).
+    row["PricingCurrency"] = "USD"
+
+
+def _on_tax(row: dict, amount_str: str) -> None:
+    row["PricingCurrencyEffectiveCost"] = amount_str
+
+
+def _on_credit(row: dict, negative_str: str) -> None:
+    row["PricingCurrencyEffectiveCost"] = negative_str
+
+
+def _on_commit_usage(usage: dict, commit_id: str, contract_id: str, effective_str: str) -> None:
+    # FOCUS 1.3 ContractApplied: the JSON link to the Contract Commitment dataset.
+    usage["ContractApplied"] = contract_applied(commit_id, contract_id, effective_str, "1.0000", "Hours")
+
+
+V13 = VersionAdapter(
+    version="1.3",
+    default_seed=1302,
+    columns=COLUMNS,
+    contract_commitment_columns=CONTRACT_COMMITMENT_COLUMNS,
+    ladder=(
+        LadderBranch("credit", 0.05, requires_credits=True),
+        LadderBranch("tax", 0.12),
+        LadderBranch("purchase", 0.20),
+        LadderBranch("split", 0.40),
+        LadderBranch("commitment", 0.58, min_remaining=6, group=True),
+    ),
+    commitment_identity_keys=_COMMITMENT_IDENTITY_KEYS,
+    emits_split_allocation=True,
+    fill_version_identity=_fill_identity,
+    on_tax_row=_on_tax,
+    on_credit_row=_on_credit,
+    on_commit_usage=_on_commit_usage,
+)

focus_data_toolkit/io/__init__.py

@@ -0,0 +1 @@
+"""Streaming/atomic I/O layer (P1.5/P1.6/P1.7)."""