trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(strategy-state): persist instance-scoped slot maps

Browse Source
This commit is contained in:
Hermes Agent
2026-08-29 15:11:43 +09:00
parent 3f94c19162
commit 4699de61cc
18 changed files with 301 additions and 646 deletions
Download Patch File Download Diff File Expand all files Collapse all files
trex_core/adapters/persistence/postgresql.py
+48 -70
View File
@@ -28,7 +28,7 @@ from trex_core.application.ports import IntentRecord
from trex_core.application.strategy_state import (
SetResult,
StrategyStateEntry,
_cas,
_STATE_CAP_BYTES,
)
from trex_core.domain.slot import Slot, SlotNotFoundError, SlotState, SlotTransitionRecord
@@ -701,13 +701,7 @@ class PostgreSQLLedgerOutbox:
class PgStrategyStateStore:
"""slot_strategy_state-backed StrategyStateStore (dcy-028 / REQ-079).
Stores opaque per-strategy state keyed by (slot_id, strategy_id). The CAS
decision is the same `_cas` used by the in-memory double; occupancy_seq and
slot_active are supplied by the caller (fetched from the slot) so the store
only owns the slot_strategy_state table.
"""
"""PostgreSQL slot-scoped strategy-instance map store."""
def __init__(self, dsn: str, *, psycopg_module: Any = None) -> None:
self._psycopg = _require_psycopg(psycopg_module)
@@ -716,71 +710,65 @@ class PgStrategyStateStore:
def set(
self,
slot_id: UUID,
strategy_id: str,
strategy_instance_id: str,
*,
expected_occupancy_seq: int,
expected_version: int,
data: str,
current_occupancy_seq: int,
slot_active: bool,
) -> SetResult:
if not slot_active:
return SetResult(ok=False, reason="slot_inactive")
if len(data.encode("utf-8")) > _STATE_CAP_BYTES:
return SetResult(ok=False, reason="state_too_large")
now = datetime.now(tz=timezone.utc)
with self._psycopg.connect(self._dsn, autocommit=False) as conn:
try:
with conn.cursor() as cur:
cur.execute(
"SELECT occupancy_seq, version, data, updated_at "
"FROM slot_strategy_state "
"WHERE slot_id = %s AND strategy_id = %s FOR UPDATE",
(slot_id, strategy_id),
)
row = cur.fetchone()
existing = (
StrategyStateEntry(
strategy_id=strategy_id,
occupancy_seq=int(row[0]),
version=int(row[1]),
data=row[2],
updated_at=row[3],
)
if row is not None
else None
)
result = _cas(
existing,
expected_occupancy_seq=expected_occupancy_seq,
expected_version=expected_version,
data=data,
current_occupancy_seq=current_occupancy_seq,
slot_active=slot_active,
)
if not result.ok:
conn.rollback()
return result
cur.execute(
"INSERT INTO slot_strategy_state "
"(slot_id, strategy_id, occupancy_seq, version, data, updated_at) "
"VALUES (%s, %s, %s, %s, %s, %s) "
"ON CONFLICT (slot_id, strategy_id) DO UPDATE SET "
"occupancy_seq = EXCLUDED.occupancy_seq, "
"version = EXCLUDED.version, data = EXCLUDED.data, "
"updated_at = EXCLUDED.updated_at",
"INSERT INTO slot_strategy_state (slot_id, data) "
"SELECT %s, jsonb_build_object(%s, jsonb_build_object("
"'version', 1, 'data', %s, 'updated_at', %s)) WHERE %s = 0 "
"ON CONFLICT (slot_id) DO UPDATE SET data = jsonb_set("
"slot_strategy_state.data, ARRAY[%s], jsonb_build_object("
"'version', %s + 1, 'data', %s, 'updated_at', %s), true) "
"WHERE COALESCE((slot_strategy_state.data -> %s ->> 'version')::bigint, 0) = %s "
"RETURNING data -> %s ->> 'version'",
(
slot_id,
strategy_id,
current_occupancy_seq,
result.version,
strategy_instance_id,
data,
datetime.now(tz=timezone.utc),
now,
expected_version,
strategy_instance_id,
expected_version,
data,
now,
strategy_instance_id,
expected_version,
strategy_instance_id,
),
)
row = cur.fetchone()
if row is None:
cur.execute(
"SELECT COALESCE((data -> %s ->> 'version')::bigint, 0) "
"FROM slot_strategy_state WHERE slot_id = %s",
(strategy_instance_id, slot_id),
)
conflict = cur.fetchone()
return SetResult(
ok=False,
reason="version_conflict",
version=int(conflict[0]) if conflict is not None else 0,
)
conn.commit()
return result
return SetResult(ok=True, version=int(row[0]))
except BaseException:
conn.rollback()
raise
def get_for_slots(
self, slot_ids: list[UUID], current_occupancy_seq: dict[UUID, int]
self, slot_ids: list[UUID]
) -> dict[UUID, dict[str, StrategyStateEntry]]:
if not slot_ids:
return {}
@@ -788,26 +776,16 @@ class PgStrategyStateStore:
with self._psycopg.connect(self._dsn) as conn:
with conn.cursor() as cur:
cur.execute(
"SELECT slot_id, strategy_id, occupancy_seq, version, data, updated_at "
"SELECT slot_id, data "
"FROM slot_strategy_state WHERE slot_id = ANY(%s)",
(list(slot_ids),),
)
for row in cur.fetchall():
sid = row[0] if isinstance(row[0], UUID) else UUID(str(row[0]))
# stale-occupancy entries are invisible (dcy-028 FR-3 defense)
if int(row[2]) != current_occupancy_seq.get(sid):
continue
out.setdefault(sid, {})[row[1]] = StrategyStateEntry(
strategy_id=row[1],
occupancy_seq=int(row[2]),
version=int(row[3]),
data=row[4],
updated_at=row[5],
)
for instance_id, entry in row[1].items():
out.setdefault(sid, {})[instance_id] = StrategyStateEntry(
version=int(entry["version"]),
data=entry["data"],
updated_at=datetime.fromisoformat(entry["updated_at"]),
)
return out
def delete_all(self, slot_id: UUID) -> None:
with self._psycopg.connect(self._dsn, autocommit=False) as conn:
with conn.cursor() as cur:
cur.execute("DELETE FROM slot_strategy_state WHERE slot_id = %s", (slot_id,))
conn.commit()
trex_core/adapters/persistence/sql/027_replace_slot_strategy_state_with_instance_map.sql
+18
View File
@@ -0,0 +1,18 @@
-- REQ-0009: state is one opaque map per slot, keyed by strategy_instance_id.
-- The old strategy_id/occupancy-scoped rows cannot be assigned an instance ID;
-- no mapping or backfill is permitted by this contract.
DO $$
BEGIN
IF EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_schema = 'public'
AND table_name = 'slot_strategy_state'
AND column_name = 'strategy_id'
) THEN
DROP TABLE slot_strategy_state;
END IF;
END $$;
CREATE TABLE slot_strategy_state (
slot_id UUID PRIMARY KEY,
data JSONB NOT NULL DEFAULT '{}'::jsonb
);
trex_core/application/messaging_handlers.py
+38 -32
View File
@@ -207,7 +207,7 @@ def make_slots_rpc_handler(
):
"""Build the RPC handler for `trex.slots.req` (REQ-073/074/116).
Request: {filter?: str, spy?: bool, strategy?: str}
Request: {filter?: str, spy?: bool, strategy?: str, strategy_instance_id?: str}
filter: "all"|"inactive"|"pending"|"holding"|"error" (default "all")
spy=true: watchdog not updated (operator view, REQ-034 CHG-01)
strategy: exact-match on strategy_name (REQ-116, optional). When specified
@@ -224,6 +224,15 @@ def make_slots_rpc_handler(
body = req.payload or {}
filter_val = str(body.get("filter") or "all").lower()
spy = bool(body.get("spy", False))
strategy_instance_id = body.get("strategy_instance_id")
if not spy and (not isinstance(strategy_instance_id, str) or not strategy_instance_id):
return RpcResponse(payload={
"slots": [],
"available_slots": None,
"degraded": False,
"reason": "bad_request:strategy_instance_id",
"message": "strategy_instance_id must be a non-empty string",
})
# REQ-116 (BAT-055): optional strategy filter — exact-match on strategy_name.
# None means no filter (all slots returned regardless of strategy_name).
strategy_filter = _opt_str(body.get("strategy"))
@@ -290,24 +299,29 @@ def make_slots_rpc_handler(
row["qty"] = None
row["qty_source"] = "unavailable"
# dcy-028 / REQ-073/074·079 (C-1): attach opaque strategy_state map per
# row via one batched store read (read piggyback — no extra round trip).
# Only entries matching the slot's current occupancy_seq are surfaced.
# Strategy requests receive only their exact entry; operator requests
# receive the complete slot map without changing watchdog behavior.
if strategy_state_store is not None and slots:
slot_ids = [s.slot_id for s in slots]
occ = {s.slot_id: getattr(s, "occupancy_seq", 0) for s in slots}
state_map = strategy_state_store.get_for_slots(slot_ids, occ)
state_map = strategy_state_store.get_for_slots(slot_ids)
for row, s in zip(slot_rows, slots, strict=True):
entries = state_map.get(s.slot_id)
if entries:
row["strategy_state"] = {
strat: {
"version": e.version,
"data": e.data,
"updated_at": e.updated_at.isoformat(),
if spy:
row["strategy_state"] = {
instance_id: {
"version": e.version,
"data": e.data,
"updated_at": e.updated_at.isoformat(),
}
for instance_id, e in entries.items()
}
elif (entry := entries.get(strategy_instance_id)) is not None:
row["strategy_state"] = {
"version": entry.version,
"data": entry.data,
"updated_at": entry.updated_at.isoformat(),
}
for strat, e in entries.items()
}
# dcy-018 / REQ-029: cash-estimated overlay (best-effort)
if ledger_outbox is not None:
@@ -406,15 +420,12 @@ def make_strategy_state_set_handler(
):
"""Build the RPC handler for `trex.slots.strategy_state.set` (REQ-080).
Request: {slot_id, strategy_id, expected_version:int,
expected_occupancy_seq:int, data:str}
Response (ok): {ok:true, slot_id, strategy_id, version:int}
Response (fail): {ok:false, slot_id, strategy_id, reason, version?|occupancy_seq?}
Request: {slot_id, strategy_instance_id, expected_version:int, data:str}
Response (ok): {ok:true, slot_id, strategy_instance_id, version:int}
Response (fail): {ok:false, slot_id, strategy_instance_id, reason, version?}
reason ∈ {occupancy_changed, version_conflict, slot_inactive,
state_too_large, bad_request:<detail>}. The store owns the CAS
(REQ-079); the handler supplies the slot's current occupancy_seq and
active-ness and never interprets `data` (opaque).
The store owns entry-version CAS; the handler supplies active-ness and never
interprets opaque data.
"""
_ACTIVE_STATES = {"pending_buy", "holding", "pending_sell"}
@@ -422,9 +433,10 @@ def make_strategy_state_set_handler(
body = req.payload or {}
try:
slot_id = UUID(str(body["slot_id"]))
strategy_id = str(body["strategy_id"])
strategy_instance_id = body["strategy_instance_id"]
if not isinstance(strategy_instance_id, str) or not strategy_instance_id:
raise ValueError("strategy_instance_id must be a non-empty string")
expected_version = int(body["expected_version"])
expected_occupancy_seq = int(body["expected_occupancy_seq"])
data = body["data"]
if not isinstance(data, str):
raise ValueError("data must be a string")
@@ -432,27 +444,23 @@ def make_strategy_state_set_handler(
return RpcResponse(payload={
"ok": False,
"slot_id": body.get("slot_id"),
"strategy_id": body.get("strategy_id"),
"strategy_instance_id": body.get("strategy_instance_id"),
"reason": f"bad_request:{exc}",
})
slot = slot_repo.fetch_slot(slot_id)
slot_active = slot is not None and slot.status.value in _ACTIVE_STATES
current_occupancy_seq = getattr(slot, "occupancy_seq", 0) if slot else 0
result = strategy_state_store.set(
slot_id,
strategy_id,
expected_occupancy_seq=expected_occupancy_seq,
strategy_instance_id,
expected_version=expected_version,
data=data,
current_occupancy_seq=current_occupancy_seq,
slot_active=slot_active,
)
payload = {
"ok": result.ok,
"slot_id": str(slot_id),
"strategy_id": strategy_id,
"strategy_instance_id": strategy_instance_id,
}
if result.ok:
payload["version"] = result.version
@@ -460,8 +468,6 @@ def make_strategy_state_set_handler(
payload["reason"] = result.reason
if result.version is not None:
payload["version"] = result.version
if result.occupancy_seq is not None:
payload["occupancy_seq"] = result.occupancy_seq
return RpcResponse(payload=payload)
return handler
trex_core/application/portfolio.py
+1 -2
View File
@@ -564,7 +564,7 @@ def slot_to_dict(
"forced_close_at": s.forced_close_at.isoformat() if s.forced_close_at else None,
"universe_detached": getattr(s, "retired_at", None) is not None,
# dcy-028/REQ-081 (BAT-042): per-occupancy guard counter — the strategy
# daemon echoes this as expected_occupancy_seq on strategy_state writes.
# Slot occupancy remains domain state; strategy-state writes do not use it.
"occupancy_seq": getattr(s, "occupancy_seq", 0),
}
@@ -638,4 +638,3 @@ def _sanitize(message: str) -> str:
break
return out[:200]
trex_core/application/strategy_state.py
+28 -110
View File
@@ -1,27 +1,4 @@
"""Slot strategy-state store (dcy-028 / REQ-079, BAT-042).
A strategy daemon (e.g. trex-tsl) accumulates opaque state across a slot's
occupancy — for a Trailing Stop Loss the peak price since entry. `evaluate()`
must stay pure, so the state cannot live in the daemon (lost on restart) nor in
an external store (orphan-cleanup problem). Since the state's lifecycle matches
the slot occupancy exactly, trex-core stores it server-side keyed by
`(slot_id, strategy_id)`, round-trips it on the slots snapshot (read), accepts
version-CAS writes via a dedicated RPC, and deletes it when the slot closes.
trex-core never interprets `data` (opaque UTF-8 string). It validates only
(1) valid UTF-8 and (2) a byte size cap — encoding (JSON/base64) is the
strategy's business (dcy-028 OQ-1).
Occupancy guard (dcy-028 R-1 / REQ-081): a permanent slot is reused, so two
occupancies of the same slot both start at version 0. A write computed against
occupancy X must not land on a later occupancy Y. The slot carries a monotonic
`occupancy_seq`; the CAS rejects a write whose `expected_occupancy_seq` differs
from the slot's current value (`occupancy_changed`). The version CAS alone
cannot catch this at the first write (0 vs 0).
Single-writer assumption: one daemon operates a given slot·strategy. The CAS is
for retry / duplicate / occupancy-turnover safety, not multi-writer concurrency.
"""
"""Slot-scoped opaque strategy-instance state."""
from __future__ import annotations
import os
@@ -31,13 +8,8 @@ from datetime import datetime, timezone
from typing import Optional, Protocol
from uuid import UUID
# dcy-028 OQ-1: hard ceiling for the opaque `data` blob, measured in UTF-8
# bytes. Operators target 1~2KB for the known TSL use case; 4KB is the cap.
_STATE_CAP_BYTES = int(os.environ.get("TREX_STRATEGY_STATE_CAP_BYTES", "4096"))
# Reject reason tokens (dcy-028 / REQ-080). The full enumerated set; consumers
# fail-closed on anything unrecognized.
REASON_OCCUPANCY_CHANGED = "occupancy_changed"
REASON_VERSION_CONFLICT = "version_conflict"
REASON_SLOT_INACTIVE = "slot_inactive"
REASON_STATE_TOO_LARGE = "state_too_large"
@@ -45,10 +17,8 @@ REASON_STATE_TOO_LARGE = "state_too_large"
@dataclass(frozen=True)
class StrategyStateEntry:
"""One stored opaque state value for a (slot_id, strategy_id)."""
"""One opaque entry in a slot's strategy_instance_id map."""
strategy_id: str
occupancy_seq: int
version: int
data: str
updated_at: datetime
@@ -56,64 +26,20 @@ class StrategyStateEntry:
@dataclass(frozen=True)
class SetResult:
"""Outcome of a CAS set. ok=True carries the new version; else `reason`."""
ok: bool
version: Optional[int] = None
reason: Optional[str] = None
occupancy_seq: Optional[int] = None # current slot occupancy_seq on conflict
def _byte_len(data: str) -> int:
return len(data.encode("utf-8"))
class StrategyStateStore(Protocol):
def set(
self,
slot_id: UUID,
strategy_id: str,
*,
expected_occupancy_seq: int,
expected_version: int,
data: str,
current_occupancy_seq: int,
slot_active: bool,
) -> SetResult:
"""occupancy_seq + version CAS upsert of opaque `data` (dcy-028 FR-2)."""
...
def get_for_slots(
self, slot_ids: list[UUID], current_occupancy_seq: dict[UUID, int]
) -> dict[UUID, dict[str, StrategyStateEntry]]:
"""Batched read for the snapshot (C-1). Returns slot_id -> {strategy_id: entry}.
Only entries whose stored occupancy_seq matches the slot's current
occupancy_seq are returned (stale entries from a prior occupancy are
invisible — defense in depth alongside close-delete, dcy-028 FR-3)."""
...
def delete_all(self, slot_id: UUID) -> None:
"""Delete all strategy_state for a slot (close hook, dcy-028 C-3)."""
...
def _cas(
existing: Optional[StrategyStateEntry],
*,
expected_occupancy_seq: int,
expected_version: int,
data: str,
current_occupancy_seq: int,
slot_active: bool,
existing: Optional[StrategyStateEntry], *, expected_version: int, data: str, slot_active: bool
) -> SetResult:
"""Pure CAS decision shared by all store implementations (dcy-028 FR-2)."""
if not slot_active:
return SetResult(ok=False, reason=REASON_SLOT_INACTIVE)
if expected_occupancy_seq != current_occupancy_seq:
return SetResult(
ok=False, reason=REASON_OCCUPANCY_CHANGED, occupancy_seq=current_occupancy_seq
)
if _byte_len(data) > _STATE_CAP_BYTES:
return SetResult(ok=False, reason=REASON_STATE_TOO_LARGE)
stored_version = existing.version if existing is not None else 0
@@ -122,62 +48,54 @@ def _cas(
return SetResult(ok=True, version=stored_version + 1)
class StrategyStateStore(Protocol):
def set(
self,
slot_id: UUID,
strategy_instance_id: str,
*,
expected_version: int,
data: str,
slot_active: bool,
) -> SetResult: ...
def get_for_slots(self, slot_ids: list[UUID]) -> dict[UUID, dict[str, StrategyStateEntry]]: ...
class InMemoryStrategyStateStore:
"""Process-local strategy-state store (paper / tests / explicit double)."""
"""Process-local slot-scoped state-map store."""
def __init__(self) -> None:
# (slot_id, strategy_id) -> StrategyStateEntry
self._store: dict[tuple[UUID, str], StrategyStateEntry] = {}
self._store: dict[UUID, dict[str, StrategyStateEntry]] = {}
self._lock = threading.Lock()
def set(
self,
slot_id: UUID,
strategy_id: str,
strategy_instance_id: str,
*,
expected_occupancy_seq: int,
expected_version: int,
data: str,
current_occupancy_seq: int,
slot_active: bool,
) -> SetResult:
with self._lock:
existing = self._store.get((slot_id, strategy_id))
entries = self._store.setdefault(slot_id, {})
existing = entries.get(strategy_instance_id)
result = _cas(
existing,
expected_occupancy_seq=expected_occupancy_seq,
expected_version=expected_version,
data=data,
current_occupancy_seq=current_occupancy_seq,
slot_active=slot_active,
existing, expected_version=expected_version, data=data, slot_active=slot_active
)
if not result.ok:
if not entries:
self._store.pop(slot_id, None)
return result
self._store[(slot_id, strategy_id)] = StrategyStateEntry(
strategy_id=strategy_id,
occupancy_seq=current_occupancy_seq,
entries[strategy_instance_id] = StrategyStateEntry(
version=result.version, # type: ignore[arg-type]
data=data,
updated_at=datetime.now(tz=timezone.utc),
)
return result
def get_for_slots(
self, slot_ids: list[UUID], current_occupancy_seq: dict[UUID, int]
) -> dict[UUID, dict[str, StrategyStateEntry]]:
def get_for_slots(self, slot_ids: list[UUID]) -> dict[UUID, dict[str, StrategyStateEntry]]:
wanted = set(slot_ids)
out: dict[UUID, dict[str, StrategyStateEntry]] = {}
with self._lock:
for (sid, strat), entry in self._store.items():
if sid not in wanted:
continue
# stale-occupancy entries are invisible (dcy-028 FR-3 defense)
if entry.occupancy_seq != current_occupancy_seq.get(sid):
continue
out.setdefault(sid, {})[strat] = entry
return out
def delete_all(self, slot_id: UUID) -> None:
with self._lock:
for key in [k for k in self._store if k[0] == slot_id]:
del self._store[key]
return {sid: dict(entries) for sid, entries in self._store.items() if sid in wanted}
trex_core/domain/slot/service.py
-7
View File
@@ -52,8 +52,6 @@ class SlotService:
# does not serialize transitions across instances (NFR-1).
self._instance_key = instance_key
self._lock_id = slot_advisory_lock_id(instance_key)
# dcy-028/REQ-081 (C-3): when injected, all strategy_state for a slot is
# deleted on close (→INACTIVE). None keeps legacy behaviour (no store).
self._strategy_state_store = strategy_state_store
@property
@@ -155,11 +153,6 @@ class SlotService:
extra=extra or {},
)
)
# dcy-028/REQ-081 (C-3): close deletes the slot's strategy_state so a
# reused slot starts empty. Covers every close path (strategy sell,
# safety-sell, forced-close, operator) since all funnel to →INACTIVE.
if to_state is SlotState.INACTIVE and self._strategy_state_store is not None:
self._strategy_state_store.delete_all(slot_id)
return updated
@staticmethod