Feat/ops foundation

[CWFred]

No description provided.

[gemini-code-assist]

Code Review

This pull request implements the foundation of the live-trading layer, introducing a guarded paper broker (GuardedBroker wrapping PaperBroker), a SQLite-based append-only event journal, and a suite of thirteen safety guardrail rules evaluated by a RuleEngine. Feedback on the implementation highlights several critical improvements: in PaperBroker, qty_to_sell should be capped to existing.quantity when within the epsilon threshold to prevent negative remaining quantities, and quote prices should be validated to be strictly positive to avoid division-by-zero errors. Additionally, CashReserveRule should explicitly reject trades resulting in negative cash to preserve the cash-only constraint under negative equity or zero-reserve configurations, and the Journal class should synchronize SQLite writes with a lock to ensure thread safety when accessed concurrently.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If qty_to_sell is slightly larger than existing.quantity but within the _EPSILON threshold, the NoSuchPosition exception is not raised. However, the code proceeds to sell qty_to_sell which exceeds the actual position quantity. This results in a negative remaining quantity and credits the account with extra proceeds (effectively creating shares/cash out of thin air). To prevent this, qty_to_sell should be capped to existing.quantity when it is within the _EPSILON boundary.

Suggested change

	if qty_to_sell > existing.quantity + _EPSILON:
	raise NoSuchPosition(
	f"sell qty {qty_to_sell} exceeds position {existing.quantity}"
	)
	if qty_to_sell > existing.quantity:
	if qty_to_sell > existing.quantity + _EPSILON:
	raise NoSuchPosition(
	f"sell qty {qty_to_sell} exceeds position {existing.quantity}"
	)
	qty_to_sell = existing.quantity

[gemini-code-assist]

In CashReserveRule, if equity is negative, the calculated floor will also be negative. Similarly, if cash_reserve_pct is configured to 0, the floor is 0. In these scenarios, checking only post_cash < floor can allow post_cash to become negative (e.g., if floor is -20, a post_cash of -15 is allowed). This violates the core cash-only / no-margin constraint. We should explicitly reject any trade that would result in negative cash.

Suggested change

	floor = equity * ctx.config.cash_reserve_pct
	post_cash = cash - ctx.order.notional_dollars
	if post_cash < floor:
	return RuleResult.reject(
	f"post-trade cash ${post_cash} below reserve floor ${floor}"
	)
	floor = equity * ctx.config.cash_reserve_pct
	post_cash = cash - ctx.order.notional_dollars
	if post_cash < 0:
	return RuleResult.reject(f"post-trade cash ${post_cash} would be negative")
	if post_cash < floor:
	return RuleResult.reject(
	f"post-trade cash ${post_cash} below reserve floor ${floor}"
	)

[gemini-code-assist]

The quote price returned by self._quote(order.symbol) is not validated. If the quote source returns a zero or negative price (e.g., due to an API error or a missing quote), it will cause a ZeroDivisionError or result in an invalid negative position quantity during the trade execution. Consider validating that price > 0 before proceeding with the order fill.

[gemini-code-assist]

Passing check_same_thread=False allows the SQLite connection to be accessed across multiple threads (such as the background PositionGuardian thread and the main Orchestrator thread). However, Python's sqlite3 connection is not thread-safe for concurrent write operations without external synchronization. To prevent database corruption or operational errors, consider adding a threading.Lock to serialize all database executions within the Journal class.