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()