source_file: ./strat.py
schema_version: v1.1

factual_summary: >
  Implements a market making strategy module responsible for maintaining
  top-of-book state, calculating bid and ask prices using threshold-based
  logic, validating tradable assets, and coordinating trade logging.
  Manages exchange instances, symbol discovery across exchanges, and
  runtime strategy state used for order placement and monitoring.

methods:
  registerExchange(exch: str, exchInst: Exchange) -> None:
    description: >
      Registers an exchange instance under a named key for use by the
      strategy during execution.

  setMinQty(exch: str, qtyMap: dict) -> None:
    description: >
      Updates minimum and maximum trade quantity constraints for a given
      exchange using a provided quantity mapping.

  printFloating(ts: float) -> None:
    description: >
      Emits a formatted runtime summary of strategy activity for logging
      and monitoring purposes.

  bestEdgeBid(exch: str, sym: str) -> List[bool, float, bool, str, float]:
    description: >
      This method is designed to determine whether and where a bid should be placed based on several factors 
      related to market conditions and strategy rules. Its primary goal of is to calculate the optimal bid price for a 
      given symbol on a specific exchange, taking into account market positions, hedging strategies, trading limits, 
      price precision, and fee structures. Returns  a collection of decision outputs including bid eligibility status, 
      relative pricing divergence, long-position participation, selected hedge exchange, and the computed bid price.

  bestEdgeOffer(exch: str, sym: str) -> list:
    description: >
      The primary goal of bestEdgeOffer is to calculate the optimal offer (ask) price for a given symbol on a specific 
      exchange, considering market positions, hedging strategies, trading limits, price precision, fee structures. 
      Returns almost identical items as bestEdgeBid, but on the other side of the order book

  updateTob(exch: str, sym: str, tob: dict, ts: float, force: bool) -> None:
    description: >
      The primary goal of the updateTob function is to update the top of the order book for quick access to perform 
      market making operations (bidding and selling) using the highest bid and lowest ask prices.

interpretive_summary: >
  Serves as the central coordination unit for the market making strategy,
  maintaining shared runtime state across exchanges and assets while
  enforcing eligibility rules and operational constraints. Designed to
  balance responsiveness with safety through internal validation,
  rate limiting counters, and symbol qualification logic.

invariants:
  - Only assets validated by runtime eligibility checks may be traded.
  - Exchange instances must be registered before strategy execution.
  - Top-of-book data must exist before bid or ask calculations occur.
  - Rate limiting counters must accurately reflect order activity.

tags:
  domain:
    - market_data
    - strategy_execution
    - order_execution
    - exchange_integration

  trading_function:
    - position_sizing
    - entry_logic
    - exit_logic

  strategy_layer:
    - execution
    - decision

  system_layer:
    - engine

  intent:
    - orchestration
    - validation
    - safety

  data_type:
    - signals
    - orders
    - positions
    - exchanges

  risk:
    - capital_loss
    - latency
    - data_corruption

  maturity:
    - production