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

session.py

1"""One execution owner drives one MarketSession and one persisted account run."""23from __future__ import annotations45from contextlib import contextmanager6from dataclasses import asdict7from threading import RLock8from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, Optional, Tuple910from sim_platform.domain.json_values import copy_json11from sim_platform.domain.models import ContractError, Intent, integer12from sim_platform.resources import cleanup, cleanup_after_error, serialized1314from .engine import snapshot_universe15from .models import ExecutionConfig, ExecutionSnapshot, Fill, Frontier16from .state import ExecutionState1718if TYPE_CHECKING:  # Annotation only: no runtime import of the market package.19    from sim_platform.market.models import MarketEvent, MarketSnapshot202122def _require_startable(23    operations: Any,24    ownership: Any,25    run: Dict[str, Any],26    profile: str,27    maker: str,28    market: Any,29) -> None:30    """Reject a run or market that cannot start a new execution session.3132    The run must be active, owned by ``maker``, configured for execution on this one33    symbol, and have no ledger history. The market must be either untouched or exactly34    at the start point saved when the experiment was prepared. Neither may already35    have an execution owner.36    """37    if run['status'] != 'running' or run['maker_id'] != maker:38        raise ContractError('run is inactive or maker has no authority')39    if 'execution' not in run['config']:40        raise ContractError('run is not configured for execution')41    ExecutionConfig(**run['config']['execution'])  # Validates the saved settings.42    # The run stores its universe sorted; the merged market keeps the chosen order.43    if sorted(run['universe']) != sorted(snapshot_universe(market.snapshot)):44        raise ContractError('execution requires the matching market symbols')45    source = run['config'].get('research_source') or {}46    origin = source.get('start_origin')47    prepared = origin == dict(48        sequence=market.snapshot.sequence, time_ns=market.time_ns49    ) and market.status in ('ready', 'paused')50    untouched = market.status == 'ready' and market.time_ns == 0 and market.snapshot.sequence == 051    if not prepared and not untouched:52        raise ContractError('bind a fresh ready market session')53    if operations.run_events(profile, run['id'], limit=1):54        raise ContractError('execution restart is unsupported; replay ledger or create a new run')55    if ownership.has_execution(run['id']) or market.has_execution_owner:56        raise ContractError('run or market already has an execution owner')575859class ExecutionSession:60    """The single owner that drives one market session for one account run.6162    Creating a session takes exclusive write access to the account, claims the run63    and the market, and records the starting position. From then on every market step64    goes through this object, so the market and the account ledger cannot drift apart.65    If the market is advanced by anyone else, the next call fails the run.6667    Ending the run (``finish``, ``fail``, ``close``) or a processing error releases68    all three claims. A session is not restartable: a finished run needs a new run.6970    Args:71        operations: Financial reads and writes (ExecutionCoordinator through Platform).72        profile: Profile that owns the run.73        run_id: The run to execute; it must be active and have no history.74        maker: Decision maker that currently holds authority for the run.75        market: The market session to drive.76        ownership: Registry that allows one execution owner per run.77    """7879    def __init__(80        self,81        operations: Any,82        profile: str,83        run_id: str,84        maker: str,85        market: Any,86        *,87        ownership: Any,88    ) -> None:89        run = operations.run(profile, run_id)90        _require_startable(operations, ownership, run, profile, maker, market)91        self._lease = operations.acquire_account(run['account_id'])92        try:93            ownership.claim_execution(run_id, self)94        except Exception:95            self._lease.close()96            raise97        try:98            market.claim_execution(self)99            operations.execution(100                'bind',101                profile,102                run_id,103                maker,104                market.snapshot,105                operations.replay_source(market.source_descriptor()),106                write=True,107            )108        except Exception:109            market.release_execution(self)110            ownership.release_execution(run_id, self)111            self._lease.close()112            raise113        # Runs with this storage mode keep their financial state in memory between114        # changes; older runs read and write the database on every market event.115        self._runtime: Optional[ExecutionState] = None116        try:117            if run['config'].get('storage') == 'runtime-v1':118                self._runtime = ExecutionState(operations, profile, run_id)119                operations.register_runtime(run_id, self._runtime)120        except Exception:121            market.release_execution(self)122            ownership.release_execution(run_id, self)123            self._lease.close()124            raise125        self._control_lock = self._runtime.lock if self._runtime else RLock()126        self._ownership = ownership127        self._on_close: Callable[[], None] = lambda: None128        self._operations, self._profile, self._run, self._maker = operations, profile, run_id, maker129        self._market = market130        self._closed = False131        # True while a market callback is running; controls are refused during it.132        self._processing = False133        self._fills: Tuple[Fill, ...] = ()134        # The market position this session last processed.135        self._sequence, self._time = market.snapshot.sequence, market.time_ns136137    @contextmanager138    def control_boundary(self) -> Iterator[None]:139        """Serialize observation and authority checks with the resulting operation."""140        with self._control_lock:141            yield142143    def on_close(self, callback: Callable[[], None]) -> None:144        """Register one callback to run when this session releases its ownership."""145        self._on_close = callback146147    @property148    @serialized149    def snapshot(self) -> ExecutionSnapshot:150        """The account with current reservations, at the last processed market position."""151        if self._runtime:152            return self._runtime.snapshot153        return self._operations.execution('snapshot', self._profile, self._run)154155    @property156    def market_snapshot(self) -> MarketSnapshot:157        return self._market.snapshot158159    @property160    def last_fills(self) -> Tuple[Fill, ...]:161        """Fills produced by the most recent market event; empty if there were none."""162        return self._fills163164    @property165    @serialized166    def account_sequence(self) -> int:167        """Committed account version without projecting a full execution view."""168        if self._runtime is not None:169            return self._runtime.account.sequence170        return self.snapshot.account.sequence171172    @property173    def closed(self) -> bool:174        return self._closed175176    @property177    @serialized178    def replay_state(self) -> Frontier:179        """A detached copy of the financial frontier, for verifying a recorded replay."""180        if self._runtime is None:181            raise ContractError('recorded replay requires runtime-v1')182        return copy_json(self._runtime.last)183184    @serialized185    def finish_recorded_replay(self, status: str, reason: str) -> ExecutionSnapshot:186        return self._finish(status, reason)187188    def validate_control(self) -> None:189        """Check lifecycle, callback reentrancy and synchronization before a decision."""190        self._check()191192    @serialized193    def adopt_maker(self, maker: str) -> None:194        """Follow an authority change only after the database has committed it."""195        self._check()196        run = self._operations.run(self._profile, self._run, include_records=False)197        if run['status'] != 'running' or run['maker_id'] != maker:198            raise ContractError('maker has no committed instruction authority')199        self._maker = maker200201    def fail(self, reason: str) -> ExecutionSnapshot:202        """Terminate a failed decision run and release its execution ownership."""203        self._check()204        return self._finish('failed', reason)205206    def _check(self) -> None:207        """Refuse a closed session, a reentrant call, or a market moved by someone else.208209        A market that advanced outside this session can no longer be reconciled with210        the ledger, so the run is failed and the market closed before raising.211        """212        if self._closed:213            raise ContractError('execution session is closed')214        if self._processing or self._market.is_notifying:215            raise ContractError('execution controls cannot run inside market callbacks')216        if self._market.snapshot.sequence != self._sequence or self._market.time_ns != self._time:217            try:218                self._finish('failed', 'market was advanced outside the execution session')219            finally:220                cleanup(self._market.close, self._unbind)221            raise ContractError('market was advanced outside the execution session')222223    @serialized224    def submit(self, intent: Intent) -> Any:225        """Submit an order directly; runs with a decision policy must use their runner."""226        self._check()227        if (228            'decision'229            in self._operations.run(self._profile, self._run, include_records=False)['config']230        ):231            raise ContractError('submit through DecisionRunner to record observation and action')232        return self._operations.direct_execution(233            'submit', self._profile, self._run, self._maker, intent, self._market.snapshot234        )235236    @serialized237    def cancel(self, order_id: str) -> Any:238        """Cancel an order directly; runs with a decision policy must use their runner."""239        self._check()240        if (241            'decision'242            in self._operations.run(self._profile, self._run, include_records=False)['config']243        ):244            raise ContractError('cancel through DecisionRunner to record observation and action')245        return self._operations.direct_execution(246            'cancel', self._profile, self._run, self._maker, order_id, self._market.snapshot247        )248249    @serialized250    def abandon(self) -> None:251        """Release execution after an untrusted storage failure, without more SQL.252253        The lifecycle owner must stop driving the market. Committed orders and254        the unresolved DB run are preserved for explicit recovery.255        """256        if not self._closed:257            self._unbind()258259    @serialized260    def play(self) -> Any:261        self._check()262        return self._market.play()263264    @serialized265    def pause(self) -> Any:266        """Pause the market and save the current financial position."""267        self._check()268        result = self._market.pause()269        self._operations.checkpoint_execution(self._profile, self._run)270        return result271272    @serialized273    def step(self) -> MarketEvent:274        """Advance a ready or paused market by exactly one event and process it."""275        self._check()276        if self._market.status not in ('ready', 'paused'):277            raise ContractError('step requires ready or paused market')278        return self._advance(self._market.step)279280    @serialized281    def pump(self, count: int = 1) -> Tuple[MarketEvent, ...]:282        """Process up to ``count`` events while the market is playing.283284        Stops early when the market stops playing or the run ends.285        """286        self._check()287        if type(count) is not int or count < 1:288            raise ContractError('pump count must be a positive integer')289        events = []290        for _ in range(count):291            if self._closed or self._market.status != 'playing':292                break293            events.append(self._advance(lambda: self._market.pump(1)[0]))294        return tuple(events)295296    def _advance(self, advance: Callable[[], MarketEvent]) -> MarketEvent:297        """Take one event from the market and apply it to the account.298299        A market that completes or fails ends the run. Any error here leaves the300        market ahead of the ledger, so the run is failed and everything released.301        """302        self._processing = True303        try:304            self._fills = ()305            event = advance()306            if event.kind in ('market', 'clock', 'news'):307                self._fills = (308                    self._runtime.advance(event)309                    if self._runtime310                    else self._operations.execution(311                        'advance', self._profile, self._run, event, write=True312                    )313                )314                self._sequence, self._time = event.sequence, event.time_ns315            elif event.snapshot.status in ('completed', 'failed'):316                status = event.snapshot.status317                self._finish(status, event.message or f'market {status}')318            return event319        except Exception as exc:320            # Native state cannot be rolled back after a database failure. Never continue.321            cleanup_after_error(322                exc,323                lambda: self._finish('failed', 'execution processing failed'),324                self._market.close,325                self._unbind,326            )327            raise328        finally:329            self._processing = False330331    @serialized332    def advance_idle_prefix(self, end_prefix: int) -> Tuple[int, Optional[MarketEvent]]:333        """Batch only immutable, no-fill source transitions on the same owner.334335        No financial submission/commit path is bypassed. A possible fill,336        publication or observer requires ordinary per-event execution.337        """338        self._check()339        if self._runtime is None:340            return 0, None341        event = self._market.idle_candidate(end_prefix)342        if event is None or not self._runtime.can_advance_idle(event.snapshot):343            return 0, None344        count = end_prefix - self._market.merged_prefix345        if event.sequence != self._sequence + count:346            raise ContractError('idle span crosses a non-source publication')347        try:348            self._runtime.advance_idle(event, count)349        except Exception:350            self.abandon()351            raise352        self._market.apply_idle(end_prefix, event)353        self._sequence, self._time = event.sequence, event.time_ns354        self._fills = ()355        return count, event356357    def _finish(self, status: str, reason: str, time_ns: Optional[int] = None) -> ExecutionSnapshot:358        """Record the end of the run, then release ownership even if recording fails."""359        if self._runtime:360            snapshot = asdict(self._market.snapshot)361            if snapshot['sequence'] != self._runtime.last['market_sequence']:362                snapshot = {**self._runtime.last['market'], 'status': 'failed', 'error': reason}363            self._runtime.last = {**self._runtime.last, 'market': snapshot}364        try:365            return self._operations.execution(366                'finish',367                self._profile,368                self._run,369                status,370                self._market.time_ns if time_ns is None else time_ns,371                reason,372                write=True,373            )374        finally:375            self._unbind()376377    def _unbind(self) -> None:378        """Release the run, the account lease and the market; the session is then closed."""379        self._closed = True380        self._ownership.release_execution(self._run, self)381        self._operations.unregister_runtime(self._run, self._runtime)382        self._lease.close()383        self._on_close()384        self._market.release_execution(self)385386    @serialized387    def finish(388        self, status: str, reason: str, *, time_ns: Optional[int] = None389    ) -> ExecutionSnapshot:390        """End at an owner clock boundary without consuming the end-time source frame."""391        self._check()392        if time_ns is not None:393            integer(time_ns, 'execution end time')394            if time_ns < self._market.time_ns:395                raise ContractError('execution end precedes the source prefix')396        return self._finish(status, reason, time_ns)397398    @serialized399    def close(self) -> None:400        """Stop the run if it is still active; closing twice is harmless."""401        if not self._closed:402            self._check()403            cleanup(lambda: self._finish('stopped', 'execution stopped by user'), self._unbind)404405    def __enter__(self) -> ExecutionSession:406        return self407408    def __exit__(self, *_: object) -> None:409        self.close()