arkhai-kit-settlement-runtime 0.1.2__py3-none-any.whl

arkhai_kit_settlement_runtime-0.1.2.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: arkhai-kit-settlement-runtime
+Version: 0.1.2
+Summary: Mechanism-neutral commercial settlement lifecycle, durable servicing, and SQLite repository.
+License-Expression: MIT
+Requires-Python: <3.14,>=3.10
+Requires-Dist: arkhai-core==0.2.0
+Requires-Dist: arkhai-kit-identity==0.3.0
+Requires-Dist: pydantic>=2.7

arkhai_kit_settlement_runtime-0.1.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+market_settlement_runtime/__init__.py,sha256=Ze__7QPyFReV6d-7zGUQ_jWnLs4r2AJtxl7v-2PlVWI,5028
+market_settlement_runtime/clauses.py,sha256=fWjRB2gKuU_d4mlqPXCDuxJk_EhXaPbRCGKz-STbL74,10977
+market_settlement_runtime/configuration.py,sha256=dLl6IvuNjVS7WiKW150nL5DmJnbduKvzZI1LCS2Emd0,42147
+market_settlement_runtime/hosted_routes.py,sha256=-RuWBn23jsadcwOxFaFJrtyW6kS8zh6nxXet5CQ1OF0,13918
+market_settlement_runtime/jobs.py,sha256=Ckjk7BwSn1-YNGzIfC-_v4BSi8h-0oCMlmzlD7Dq96g,5759
+market_settlement_runtime/models.py,sha256=l04V4PIimNjA207TLWkgtlLUGGDG4I4CI8oVtUaAPKE,8411
+market_settlement_runtime/policy.py,sha256=S8S1EsyWzF4FjnvkN5XGAbIexvAvogm0dZ751IlhL_A,2660
+market_settlement_runtime/ports.py,sha256=vum4jPQ4Snjyp8q43JVRbaNep7TYdnwuDu0IlqBo6ps,4402
+market_settlement_runtime/publication.py,sha256=xfq1RrvBYrYuwdUt7ZVhoDBnWDvTxOmupQx2-RVDPcY,8790
+market_settlement_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+market_settlement_runtime/runtime.py,sha256=hUFSoMEiGspJZ1DSfkRAAKhLQtZLO_mVP3BZ7uF8HAg,35069
+market_settlement_runtime/servicing.py,sha256=-c3m7i7ECslGH3YoHxFdL2flj4HzNzLd1Inum-5WJXY,12254
+market_settlement_runtime/sqlite_repository.py,sha256=iw7DCjo6QBAm6P6Ien6VoDyr6f2WdPOiknCvI5j0juo,64954
+arkhai_kit_settlement_runtime-0.1.2.dist-info/METADATA,sha256=KEnrvE9Y-fmT7PZF2x02v1EDUMKx7unjzI99BkLRL8Y,334
+arkhai_kit_settlement_runtime-0.1.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+arkhai_kit_settlement_runtime-0.1.2.dist-info/RECORD,,

arkhai_kit_settlement_runtime-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

market_settlement_runtime/__init__.py

@@ -0,0 +1,191 @@
+"""One durable, mechanism-neutral commercial settlement runtime."""
+
+from market_core.query_dsl import (
+    ComparisonOperator,
+    FieldDescriptor,
+    MissingValueRule,
+    QueryValueType,
+)
+from .clauses import (
+    CompiledSettlementClause,
+    SettlementCandidate,
+    SettlementClauseResult,
+    compile_settlement_clause,
+    select_settlement_candidates,
+    settlement_clause_descriptors,
+    settlement_clause_matches,
+)
+from .configuration import (
+    SETTLEMENT_CONFIG_SCHEMA_VERSION,
+    AcceptedObligationArtifacts,
+    AcceptedObligationBuilder,
+    BuyerCompatibilityHook,
+    ClientFactory,
+    MechanismReadiness,
+    MechanismRegistration,
+    OptionBuilder,
+    PreflightCallback,
+    PublicationInputValidator,
+    ReadinessBlocker,
+    RegisteredSettlementClauseField,
+    SettlementClauseField,
+    SettlementClauseProjector,
+    SettlementConfig,
+    SettlementConfigurationError,
+    SettlementConfigurationRegistry,
+    SettlementRole,
+)
+from .jobs import (
+    FulfillmentOutcome,
+    PreparedSettlement,
+    SettlementJobCoordinator,
+)
+from .hosted_routes import (
+    AuthorizedSettlementRequest,
+    BeforeHostedReclaim,
+    HostedAcceptedAgreement,
+    HostedSettlementRouteCallbacks,
+    HostedSettlementRouteError,
+    HostedSettlementRouteService,
+    HostedSettlementStart,
+)
+from .models import (
+    ConditionDecision,
+    ConditionOutcome,
+    ConditionState,
+    EffectOutcome,
+    EscrowStatus,
+    MaterializationOutcome,
+    MaterializationState,
+    MaterializationStatus,
+    OperationKind,
+    OperationState,
+    Party,
+    SettlementObligationRecord,
+    SettlementOperationOutcome,
+    SettlementOperationRecord,
+    SettlementPlanStatus,
+    StatusOutcome,
+    TerminalEffectState,
+    aggregate_settlement_status,
+    canonical_json,
+    derive_obligation_ref,
+    obligation_payload_hash,
+)
+from .policy import (
+    FailureActionHandler,
+    FailurePolicy,
+    FailurePolicyResult,
+)
+from .ports import (
+    ConditionalEscrowClient,
+    SettlementRuntimeRepository,
+    SettlementServicingRepository,
+)
+from .runtime import (
+    MANUAL_REASON_KEY,
+    SettlementManualRequired,
+    SettlementRuntime,
+    settlement_operation_ref,
+)
+from .publication import (
+    SettlementPublicationClause,
+    compile_settlement_publication_clause,
+)
+from .servicing import (
+    EventCallback,
+    SettlementServicingWorker,
+    TerminalCallback,
+)
+from .sqlite_repository import (
+    SETTLEMENT_MIGRATION_ID,
+    SETTLEMENT_MECHANISM_PARAMS_MIGRATION_ID,
+    SETTLEMENT_PRINCIPAL_MIGRATION_ID,
+    SettlementMigration,
+    SettlementSQLiteRepository,
+    settlement_migrations,
+)
+
+__all__ = [
+    "SETTLEMENT_CONFIG_SCHEMA_VERSION",
+    "AcceptedObligationArtifacts",
+    "AcceptedObligationBuilder",
+    "SETTLEMENT_MIGRATION_ID",
+    "SETTLEMENT_MECHANISM_PARAMS_MIGRATION_ID",
+    "SETTLEMENT_PRINCIPAL_MIGRATION_ID",
+    "CompiledSettlementClause",
+    "ComparisonOperator",
+    "BuyerCompatibilityHook",
+    "ClientFactory",
+    "SettlementCandidate",
+    "SettlementClauseField",
+    "SettlementClauseProjector",
+    "SettlementClauseResult",
+    "ConditionDecision",
+    "ConditionOutcome",
+    "ConditionState",
+    "ConditionalEscrowClient",
+    "AuthorizedSettlementRequest",
+    "BeforeHostedReclaim",
+    "HostedAcceptedAgreement",
+    "HostedSettlementRouteCallbacks",
+    "HostedSettlementRouteError",
+    "HostedSettlementRouteService",
+    "HostedSettlementStart",
+    "EffectOutcome",
+    "EscrowStatus",
+    "FieldDescriptor",
+    "EventCallback",
+    "FailureActionHandler",
+    "FailurePolicy",
+    "FailurePolicyResult",
+    "FulfillmentOutcome",
+    "MaterializationOutcome",
+    "MaterializationState",
+    "MaterializationStatus",
+    "MechanismReadiness",
+    "MechanismRegistration",
+    "OperationKind",
+    "OperationState",
+    "MissingValueRule",
+    "OptionBuilder",
+    "Party",
+    "PreflightCallback",
+    "PublicationInputValidator",
+    "PreparedSettlement",
+    "ReadinessBlocker",
+    "RegisteredSettlementClauseField",
+    "SettlementConfig",
+    "QueryValueType",
+    "SettlementConfigurationError",
+    "SettlementConfigurationRegistry",
+    "SettlementJobCoordinator",
+    "MANUAL_REASON_KEY",
+    "SettlementManualRequired",
+    "SettlementMigration",
+    "SettlementObligationRecord",
+    "SettlementOperationOutcome",
+    "SettlementOperationRecord",
+    "SettlementPlanStatus",
+    "SettlementPublicationClause",
+    "SettlementRole",
+    "SettlementRuntime",
+    "SettlementRuntimeRepository",
+    "SettlementSQLiteRepository",
+    "SettlementServicingRepository",
+    "SettlementServicingWorker",
+    "StatusOutcome",
+    "TerminalCallback",
+    "TerminalEffectState",
+    "aggregate_settlement_status",
+    "canonical_json",
+    "derive_obligation_ref",
+    "obligation_payload_hash",
+    "settlement_migrations",
+    "settlement_operation_ref",
+    "compile_settlement_publication_clause",
+    "compile_settlement_clause",
+    "select_settlement_candidates",
+    "settlement_clause_descriptors",
+    "settlement_clause_matches",
+]

market_settlement_runtime/clauses.py

@@ -0,0 +1,318 @@
+"""Typed settlement-clause compilation and same-option evaluation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any
+
+from market_core.query_dsl import (
+    ComparisonOperator,
+    FieldDescriptor,
+    MissingValueRule,
+    QueryValidationError,
+    QueryValueType,
+    ScalarValue,
+    ValidatedComparison,
+    ValidatedQuery,
+    compile_query,
+)
+from market_core.schemas import SettlementOption
+
+from .configuration import (
+    MechanismRegistration,
+    RegisteredSettlementClauseField,
+    SettlementConfig,
+    SettlementConfigurationError,
+    SettlementConfigurationRegistry,
+    SettlementRole,
+)
+
+_COMMON_OPERATORS = frozenset(
+    {
+        ComparisonOperator.EQUAL,
+        ComparisonOperator.NOT_EQUAL,
+        ComparisonOperator.IN,
+        ComparisonOperator.NOT_IN,
+    }
+)
+_COMMON_FIELDS = (
+    FieldDescriptor(
+        name="mechanism",
+        value_type=QueryValueType.STRING,
+        operators=_COMMON_OPERATORS,
+        description="canonical settlement mechanism ID or configuration key",
+    ),
+    FieldDescriptor(
+        name="asset",
+        value_type=QueryValueType.STRING,
+        operators=_COMMON_OPERATORS,
+        description="public settlement asset",
+    ),
+    FieldDescriptor(
+        name="option_id",
+        value_type=QueryValueType.STRING,
+        operators=_COMMON_OPERATORS,
+        description="immutable settlement option ID",
+    ),
+)
+_MISSING = object()
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledSettlementClause:
+    """One validated conjunction over one advertised settlement option."""
+
+    query: ValidatedQuery
+
+    def render(self) -> str:
+        return self.query.render()
+
+
+@dataclass(frozen=True, slots=True)
+class SettlementCandidate:
+    """One installed, enabled, role-compatible advertised option."""
+
+    registration: MechanismRegistration
+    option: SettlementOption
+
+
+@dataclass(frozen=True, slots=True)
+class SettlementClauseResult:
+    """Priority-ordered survivors from the first accepted explicit clause."""
+
+    candidates: tuple[SettlementCandidate, ...]
+    matched_clause_index: int | None
+
+
+def settlement_clause_descriptors(
+    registry: SettlementConfigurationRegistry,
+    *,
+    role: SettlementRole,
+) -> tuple[FieldDescriptor, ...]:
+    """Return common and role-applicable mechanism fields deterministically."""
+
+    contributed = tuple(
+        item.field.descriptor for item in registry.clause_fields(role=role)
+    )
+    return (*_COMMON_FIELDS, *contributed)
+
+
+def compile_settlement_clause(
+    source: str,
+    registry: SettlementConfigurationRegistry,
+    *,
+    role: SettlementRole = "buyer",
+) -> CompiledSettlementClause:
+    """Compile one clause and normalize public mechanism aliases."""
+
+    query = compile_query(source, settlement_clause_descriptors(registry, role=role))
+    comparisons: list[ValidatedComparison] = []
+    for comparison in query.comparisons:
+        if comparison.field != "mechanism":
+            comparisons.append(comparison)
+            continue
+        value = comparison.value
+        values = value if isinstance(value, tuple) else (value,)
+        normalized: list[ScalarValue] = []
+        for item in values:
+            assert isinstance(item, str)
+            try:
+                normalized.append(registry.canonical_mechanism_id(item, role=role))
+            except SettlementConfigurationError as exc:
+                raise QueryValidationError(
+                    "unknown_mechanism",
+                    f"unknown or role-inapplicable settlement mechanism at position {comparison.span.start}",
+                    position=comparison.span.start,
+                    field="mechanism",
+                    accepted_fields=("mechanism",),
+                ) from exc
+        comparisons.append(
+            ValidatedComparison(
+                field=comparison.field,
+                operator=comparison.operator,
+                value=tuple(normalized) if isinstance(value, tuple) else normalized[0],
+                span=comparison.span,
+            )
+        )
+    return CompiledSettlementClause(ValidatedQuery(tuple(comparisons)))
+
+
+def settlement_clause_matches(
+    clause: CompiledSettlementClause,
+    option: SettlementOption,
+    registry: SettlementConfigurationRegistry,
+    *,
+    role: SettlementRole = "buyer",
+) -> bool:
+    """Evaluate every predicate against the same immutable option."""
+
+    contributed = _field_bindings(registry, role=role)
+    descriptors = {
+        descriptor.name: descriptor
+        for descriptor in settlement_clause_descriptors(registry, role=role)
+    }
+    for comparison in clause.query.comparisons:
+        descriptor = descriptors[comparison.field]
+        actual: Any
+        if comparison.field == "mechanism":
+            actual = option.mechanism
+        elif comparison.field == "asset":
+            actual = option.asset
+        elif comparison.field == "option_id":
+            actual = option.option_id
+        else:
+            binding = contributed[comparison.field]
+            if option.mechanism != binding.mechanism_id:
+                return False
+            actual = binding.field.projector(option)
+            if actual is None or (
+                isinstance(actual, Sequence)
+                and not isinstance(actual, (str, bytes))
+                and not actual
+            ):
+                actual = _MISSING
+        if actual is _MISSING:
+            if descriptor.on_missing is MissingValueRule.PASS:
+                continue
+            return False
+        projected = _validated_projection(actual, descriptor)
+        if not _comparison_matches(comparison, projected):
+            return False
+    return True
+
+
+def select_settlement_candidates(
+    advertised: Iterable[SettlementOption | Mapping[str, Any]],
+    *,
+    registry: SettlementConfigurationRegistry,
+    config: SettlementConfig,
+    clauses: Iterable[str | CompiledSettlementClause] = (),
+    public_context: Mapping[str, Any] | None = None,
+) -> SettlementClauseResult:
+    """Admit compatible options, then apply ordered clause alternatives."""
+
+    registry.validate(config, role="buyer")
+    decoded = tuple(SettlementOption.model_validate(option) for option in advertised)
+    by_mechanism: dict[str, list[SettlementOption]] = {}
+    for option in decoded:
+        by_mechanism.setdefault(option.mechanism, []).append(option)
+
+    candidates: list[SettlementCandidate] = []
+    for registration in registry.ordered_registrations(config, role="buyer"):
+        section = config.mechanism_config(registration.config_key)
+        if section is None or not bool(getattr(section, "enabled", False)):
+            continue
+        for option in sorted(
+            by_mechanism.get(registration.mechanism_id, ()),
+            key=lambda candidate: candidate.option_id,
+        ):
+            if registry.buyer_compatible(
+                registration.mechanism_id,
+                option,
+                config,
+                public_context=public_context,
+            ):
+                candidates.append(SettlementCandidate(registration, option))
+
+    compiled = tuple(
+        clause
+        if isinstance(clause, CompiledSettlementClause)
+        else compile_settlement_clause(clause, registry, role="buyer")
+        for clause in clauses
+    )
+    if not compiled:
+        return SettlementClauseResult(tuple(candidates), None)
+    for index, clause in enumerate(compiled):
+        survivors = tuple(
+            candidate
+            for candidate in candidates
+            if settlement_clause_matches(
+                clause,
+                candidate.option,
+                registry,
+                role="buyer",
+            )
+        )
+        if survivors:
+            return SettlementClauseResult(survivors, index)
+    return SettlementClauseResult((), None)
+
+
+def _field_bindings(
+    registry: SettlementConfigurationRegistry,
+    *,
+    role: SettlementRole,
+) -> dict[str, RegisteredSettlementClauseField]:
+    bindings: dict[str, RegisteredSettlementClauseField] = {}
+    for item in registry.clause_fields(role=role):
+        bindings[item.field.descriptor.name] = item
+        for alias in item.field.descriptor.aliases:
+            bindings[alias] = item
+    return bindings
+
+
+def _validated_projection(
+    actual: Any,
+    descriptor: FieldDescriptor,
+) -> tuple[ScalarValue, ...]:
+    values = (
+        tuple(actual)
+        if isinstance(actual, Sequence) and not isinstance(actual, (str, bytes))
+        else (actual,)
+    )
+    if not values:
+        raise SettlementConfigurationError(
+            f"projector for {descriptor.name!r} returned an empty value"
+        )
+    normalized: list[ScalarValue] = []
+    for value in values:
+        if descriptor.value_type is QueryValueType.STRING:
+            valid = isinstance(value, str)
+            converted: ScalarValue = value
+        elif descriptor.value_type is QueryValueType.INTEGER:
+            valid = isinstance(value, int) and not isinstance(value, bool)
+            converted = value
+        elif descriptor.value_type is QueryValueType.DECIMAL:
+            valid = isinstance(value, (int, Decimal)) and not isinstance(value, bool)
+            converted = Decimal(value) if valid else value
+        else:
+            valid = isinstance(value, bool)
+            converted = value
+        if not valid:
+            raise SettlementConfigurationError(
+                f"projector for {descriptor.name!r} returned the wrong value type"
+            )
+        normalized.append(converted)
+    return tuple(normalized)
+
+
+def _comparison_matches(
+    comparison: ValidatedComparison,
+    actual: tuple[ScalarValue, ...],
+) -> bool:
+    expected = comparison.value
+    operator = comparison.operator
+    if operator is ComparisonOperator.EQUAL:
+        assert not isinstance(expected, tuple)
+        return any(value == expected for value in actual)
+    if operator is ComparisonOperator.NOT_EQUAL:
+        assert not isinstance(expected, tuple)
+        return all(value != expected for value in actual)
+    if operator is ComparisonOperator.IN:
+        assert isinstance(expected, tuple)
+        return any(value in expected for value in actual)
+    if operator is ComparisonOperator.NOT_IN:
+        assert isinstance(expected, tuple)
+        return all(value not in expected for value in actual)
+    assert not isinstance(expected, tuple)
+    if operator is ComparisonOperator.LESS_THAN:
+        return any(value < expected for value in actual)
+    if operator is ComparisonOperator.LESS_THAN_OR_EQUAL:
+        return any(value <= expected for value in actual)
+    if operator is ComparisonOperator.GREATER_THAN:
+        return any(value > expected for value in actual)
+    if operator is ComparisonOperator.GREATER_THAN_OR_EQUAL:
+        return any(value >= expected for value in actual)
+    raise AssertionError(f"unsupported comparison operator {operator}")