m/market labResearch, with a record.
Source on GitHub ↗

coordinator.py

1"""Execution coordination over injected transactions and owner registry; no SQL."""23from __future__ import annotations45from contextlib import nullcontext6import logging7from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple89from sim_platform.domain.json_values import copy_json10from sim_platform.domain.models import ContractError, integer1112from .models import Frontier1314_log = logging.getLogger(__name__)1516if TYPE_CHECKING:  # Annotation only: no runtime import of the market package or state owner.17    from sim_platform.market.models import MarketSnapshot1819    from .state import ExecutionState2021# Read requests up to this size are answered from the running owner's memory.22RUNTIME_HISTORY_LIMIT = 100232425class ExecutionCoordinator:26    """Route every financial read and write for a run through one place.2728    A run that is executing has an owner holding its state in memory (ExecutionState).29    For such a run the coordinator serializes each change with the owner's lock, runs30    it as one database transaction, and installs the committed result in the owner's31    memory afterwards. Small reads are answered from that memory; larger reads, and32    runs with no resident owner, go to the database.3334    Args:35        operations: Opens transactions (`execution_change`) and plain reads.36        registry: Tracks which runs have a resident owner.37        source_identity: Describes a market source for a later recorded replay.38        lease_factory: Acquires exclusive write access to an account.39        lineage: Optional ``lineage(event, profile, run_id)`` called after a run binds40            ('bind') or ends ('finish'); its failures are logged, never raised.41    """4243    def __init__(44        self,45        operations: Any,46        registry: Any,47        *,48        source_identity: Callable[..., Any],49        lease_factory: Callable[[str], Any],50        lineage: Optional[Callable[[str, str, str], None]] = None,51    ) -> None:52        self.lineage = lineage53        self.database = operations54        self.registry = registry55        self.replay_source = source_identity56        self.acquire_account = lease_factory5758    def register_runtime(self, run_id: str, runtime: Optional[ExecutionState]) -> None:59        self.registry.register_runtime(run_id, runtime)6061    def unregister_runtime(self, run_id: str, runtime: Optional[ExecutionState]) -> None:62        self.registry.unregister_runtime(run_id, runtime)6364    def _write(65        self,66        profile: str,67        run_id: str,68        operation: Callable[[Any], Any],69        *,70        state: Optional[Frontier] = None,71    ) -> Any:72        """Run ``operation`` in one transaction, then publish its result to the owner.7374        ``operation`` receives the transaction's ExecutionService. ``state`` is the75        frontier to save with the change; by default the owner supplies the next one.76        The owner's memory is updated only after the transaction has committed.77        """78        runtime = self.registry.runtime(run_id)79        with runtime.lock if runtime else nullcontext():80            previous = runtime.publication() if runtime else None81            proposed = (82                state if state is not None else runtime.operation_state() if runtime else None83            )84            change = self.database.execution_change(85                profile, run_id, operation, state=proposed, previous=previous86            )87            if runtime:88                runtime.update(change.publication)89            return change.result9091    def run(self, profile: str, run_id: str, *, include_records: bool = True) -> Dict[str, Any]:92        """Return the run's details; without records, a resident owner answers from memory."""93        runtime = self.registry.runtime(run_id)94        if runtime is not None and runtime.profile == profile and not include_records:95            with runtime.lock:96                value = copy_json(runtime.run)97                value['time_ns'] = runtime.last['market']['time_ns']98                return value99        return self.database.run(profile, run_id, include_records=include_records)100101    def decision_journal(self, profile: str, run_id: str) -> Dict[str, Any]:102        """Return the run's decision journal (its saved policy state)."""103        runtime = self.registry.runtime(run_id)104        if runtime is not None and runtime.profile == profile:105            with runtime.lock:106                return copy_json(runtime.run['policy_state'])107        return self.database.run(profile, run_id, include_records=False)['policy_state']108109    def decision_authority(self, profile: str, run_id: str) -> Tuple[str, str, int]:110        """Return (run status, current decision maker ID, handoff generation)."""111        runtime = self.registry.runtime(run_id)112        with runtime.lock if runtime else nullcontext():113            run = (114                runtime.run115                if runtime and runtime.profile == profile116                else self.database.run(profile, run_id, include_records=False)117            )118            return run['status'], run['maker_id'], run['policy_state'].get('generation', 0)119120    def decision_summaries(121        self, profile: str, run_id: str, *, limit: int = RUNTIME_HISTORY_LIMIT122    ) -> List[Dict[str, Any]]:123        """Return the most recent decision summaries, newest last."""124        integer(limit, 'record limit', 1)125        runtime = self.registry.runtime(run_id)126        if runtime is not None and runtime.profile == profile and limit <= RUNTIME_HISTORY_LIMIT:127            with runtime.lock:128                return copy_json(runtime.decisions[-limit:])129        return self.database.decision_summaries(profile, run_id, limit=limit)130131    def run_events(132        self, profile: str, run_id: str, *, limit: Optional[int] = None133    ) -> List[Dict[str, Any]]:134        """Return the run's ledger events; ``limit`` keeps only the most recent ones."""135        if limit is not None:136            integer(limit, 'event limit', 1)137        runtime = self.registry.runtime(run_id)138        if (139            runtime is not None140            and runtime.profile == profile141            and limit is not None142            and limit <= RUNTIME_HISTORY_LIMIT143        ):144            with runtime.lock:145                return copy_json(runtime.events[-limit:])146        return self.database.run_events(profile, run_id, limit=limit)147148    def execution(149        self,150        method: str,151        *args: Any,152        write: bool = False,153        runtime_state: Optional[Frontier] = None,154    ) -> Any:155        """Call the named ExecutionService method; ``args`` start with profile and run ID.156157        ``write=True`` runs it as a financial change. A snapshot of a run with a158        resident owner is answered from memory.159        """160        profile, run_id = args[:2]161        runtime = self.registry.runtime(run_id)162        if runtime and method == 'snapshot':163            if runtime.profile != profile:164                raise ContractError('profile does not own this object')165            with runtime.lock:166                return runtime.snapshot167        if write:168            result = self._write(169                profile,170                run_id,171                lambda service: getattr(service, method)(*args),172                state=runtime_state,173            )174            if self.lineage is not None and method in ('bind', 'finish'):175                try:176                    self.lineage(method, profile, run_id)177                except Exception:178                    _log.warning('Could not record lineage of run %s', run_id, exc_info=True)179            return result180        return self.database.execution_read(method, *args)181182    def direct_execution(183        self,184        method: str,185        profile: str,186        run_id: str,187        maker: str,188        value: Any,189        market: MarketSnapshot,190    ) -> Any:191        """Submit or cancel outside a decision runner.192193        The service returns a rejection instead of raising, so that a run which journals194        its operations can commit the failed attempt; the rejection is raised here.195        """196        result = self._write(197            profile,198            run_id,199            lambda service: service.direct_operation(method, profile, run_id, maker, value, market),200        )201        if isinstance(result, ContractError):202            raise result203        return result204205    def checkpoint_execution(self, profile: str, run_id: str) -> None:206        """Save a resident owner's current position; a run without one has nothing to save."""207        runtime = self.registry.runtime(run_id)208        if runtime:209            self._write(profile, run_id, lambda service: None, state=runtime.last)210211    def initialize_decisions(self, profile: str, run_id: str, maker: str) -> None:212        """Create the run's decision journal for its first decision maker."""213        from sim_platform.decisions.service import initialize_decisions214215        runtime = self.registry.runtime(run_id)216        self._write(217            profile,218            run_id,219            lambda service: initialize_decisions(service, profile, run_id, maker),220            state=runtime.last if runtime else None,221        )222223    def commit_decision(224        self,225        profile: str,226        run_id: str,227        maker: str,228        market: MarketSnapshot,229        record: Optional[Dict[str, Any]] = None,230        expected_state: Any = None,231        *,232        action: Any = None,233        position: Optional[Dict[str, Any]] = None,234    ) -> Any:235        """Shared policy/tool financial submission; tools do not write policy audit."""236        from sim_platform.decisions.service import commit237238        return self._write(239            profile,240            run_id,241            lambda service: commit(242                service,243                profile,244                run_id,245                maker,246                market,247                record,248                expected_state,249                action=action,250                position=position,251            ),252        )253254    def handoff(self, method: str, *args: Any) -> Any:255        """Run the named policy-handoff function; ``args`` start with profile and run ID."""256        from sim_platform.decisions.policy import handoffs257258        return self._write(259            args[0], args[1], lambda service: getattr(handoffs, method)(service, *args)260        )261262    def managed_handoff(self, method: str, profile: str, run_id: str, *args: Any) -> Any:263        """Run a handoff requested through the managed decision service."""264        from sim_platform.decisions.service import managed_handoff265266        return self._write(267            profile,268            run_id,269            lambda service: managed_handoff(service, method, profile, run_id, *args),270        )271272    def abort_execution_run(self, profile: str, run_id: str) -> Any:273        """Stop a run that has no live owner, for example after an interrupted session."""274        if self.registry.has_execution(run_id):275            raise ContractError('close the active execution owner instead')276        run = self.run(profile, run_id, include_records=False)277        lease = self.acquire_account(run['account_id'])278        try:279            return self.execution(280                'finish',281                profile,282                run_id,283                'stopped',284                run['time_ns'],285                'explicit recovery stop',286                write=True,287            )288        finally:289            lease.close()