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