programgarden-core 1.25.2__tar.gz → 1.26.0__tar.gz

{programgarden_core-1.25.2 → programgarden_core-1.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 1.25.2
+Version: 1.26.0
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -101,3 +101,25 @@ programgarden_core/
 
 자세한 변경 사항은 `CHANGELOG.md`를 참고하세요.
 
+## Workflow PnL event contract
+
+Futures workflow PnL events preserve native gross estimates separately from
+accounting results. `workflow_*`, `other_*`, `total_*`, account and competition
+monetary/rate scalars remain null when accounting evidence is unavailable.
+`pnl_by_currency` contains gross price-change subtotals by contract currency;
+`monetary_positions` retains their basis/status and unmodified, unconfirmed
+`broker_pnl_amount`. No fee, FX, margin/equity return or verified contest score
+is inferred from these estimates. Actual zero and negative amounts are retained.
+`currency` is null for mixed or unavailable currencies. Consumers must handle
+nullable monetary fields and must not coerce them to zero.
+
+`WorkflowPnLEvent.personal_metrics` is an optional versioned envelope for retained
+local workflow executions. Version 1 includes `scope` (kind, product, provider,
+trading mode), timezone-aware `as_of`, `basis`, executed-order count/status,
+per-symbol/exchange/currency realized amounts/status, and unavailable MDD.
+It is unverified personal evidence, independent of whole-account contest results.
+Stock realized amounts are stored long-only FIFO gross values excluding fees;
+unknown currency stays null. Futures monetary values and portfolio MDD require
+accounting evidence absent from this ledger and remain null. Consumers must
+preserve null/status and use the latest cumulative observation, not sum dates.
+

{programgarden_core-1.25.2 → programgarden_core-1.26.0}/README.md

@@ -85,3 +85,25 @@ programgarden_core/
 ## 변경 로그
 
 자세한 변경 사항은 `CHANGELOG.md`를 참고하세요.
+
+## Workflow PnL event contract
+
+Futures workflow PnL events preserve native gross estimates separately from
+accounting results. `workflow_*`, `other_*`, `total_*`, account and competition
+monetary/rate scalars remain null when accounting evidence is unavailable.
+`pnl_by_currency` contains gross price-change subtotals by contract currency;
+`monetary_positions` retains their basis/status and unmodified, unconfirmed
+`broker_pnl_amount`. No fee, FX, margin/equity return or verified contest score
+is inferred from these estimates. Actual zero and negative amounts are retained.
+`currency` is null for mixed or unavailable currencies. Consumers must handle
+nullable monetary fields and must not coerce them to zero.
+
+`WorkflowPnLEvent.personal_metrics` is an optional versioned envelope for retained
+local workflow executions. Version 1 includes `scope` (kind, product, provider,
+trading mode), timezone-aware `as_of`, `basis`, executed-order count/status,
+per-symbol/exchange/currency realized amounts/status, and unavailable MDD.
+It is unverified personal evidence, independent of whole-account contest results.
+Stock realized amounts are stored long-only FIFO gross values excluding fees;
+unknown currency stays null. Futures monetary values and portfolio MDD require
+accounting evidence absent from this ledger and remain null. Consumers must
+preserve null/status and use the latest cumulative observation, not sum dates.

{programgarden_core-1.25.2 → programgarden_core-1.26.0}/programgarden_core/bases/listener.py

@@ -205,8 +205,11 @@ class WorkflowPnLEvent:
     WorkflowPnLEvent separates workflow positions from manual positions
     using FIFO (First-In-First-Out) tracking.
     
-    Used for competition ranking where only workflow-generated trades
-    should be counted for official scoring.
+    This is a local workflow observation. Official competition scoring requires
+    separate broker-verified accounting and must not trust this event alone.
+    Futures monetary scalars are unavailable until their accounting basis is
+    established. Native gross price-change estimates remain in pnl_by_currency
+    and monetary_positions, separately from unconfirmed broker-reported values.
     
     Attributes:
         job_id: Job identifier
@@ -295,9 +298,7 @@ class WorkflowPnLEvent:
                 super().__init__(start_date="20260115")  # 대회 시작일
             
             async def on_workflow_pnl_update(self, event: WorkflowPnLEvent) -> None:
-                # Use workflow_pnl_rate for official competition ranking
-                await update_leaderboard(event.job_id, event.workflow_pnl_rate)
-                # Use competition_workflow_pnl_rate if start_date filtering is needed
+                # Display available local estimates without verifying a score.
                 if event.competition_workflow_pnl_rate is not None:
                     print(f"Competition P&L: {event.competition_workflow_pnl_rate}%")
     """
@@ -306,22 +307,22 @@ class WorkflowPnLEvent:
     product: str  # "overseas_stock" | "overseas_futures" | "korea_stock"
 
     # Workflow position P&L
-    workflow_pnl_rate: Union[Decimal, float]
-    workflow_eval_amount: Union[Decimal, float]
-    workflow_buy_amount: Union[Decimal, float]
-    workflow_pnl_amount: Union[Decimal, float]
+    workflow_pnl_rate: Optional[Union[Decimal, float]]
+    workflow_eval_amount: Optional[Union[Decimal, float]]
+    workflow_buy_amount: Optional[Union[Decimal, float]]
+    workflow_pnl_amount: Optional[Union[Decimal, float]]
     
     # Other (manual/unknown) position P&L
-    other_pnl_rate: Union[Decimal, float]
-    other_eval_amount: Union[Decimal, float]
-    other_buy_amount: Union[Decimal, float]
-    other_pnl_amount: Union[Decimal, float]
+    other_pnl_rate: Optional[Union[Decimal, float]]
+    other_eval_amount: Optional[Union[Decimal, float]]
+    other_buy_amount: Optional[Union[Decimal, float]]
+    other_pnl_amount: Optional[Union[Decimal, float]]
     
     # Total account P&L
-    total_pnl_rate: Union[Decimal, float]
-    total_eval_amount: Union[Decimal, float]
-    total_buy_amount: Union[Decimal, float]
-    total_pnl_amount: Union[Decimal, float]
+    total_pnl_rate: Optional[Union[Decimal, float]]
+    total_eval_amount: Optional[Union[Decimal, float]]
+    total_buy_amount: Optional[Union[Decimal, float]]
+    total_pnl_amount: Optional[Union[Decimal, float]]
     
     # Position details
     workflow_positions: list = field(default_factory=list)  # List[PositionDetail]
@@ -335,9 +336,19 @@ class WorkflowPnLEvent:
     paper_trading: bool = False  # True: 모의투자, False: 실전투자
 
     # Metadata
-    currency: str = "USD"
+    currency: Optional[str] = "USD"
     timestamp: datetime = field(default_factory=datetime.utcnow)
     
+    # Native estimates and broker observations are distinct from account returns.
+    monetary_status: Optional[str] = None
+    monetary_basis: Optional[str] = None
+    monetary_unavailable_reason: Optional[str] = None
+    pnl_by_currency: Dict[str, Any] = field(default_factory=dict)
+    monetary_positions: Dict[str, Any] = field(default_factory=dict)
+    unavailable_position_count: int = 0
+    # Unverified retained workflow executions; separate from account/contest PnL.
+    personal_metrics: Optional[Dict[str, Any]] = None
+
     # ========== NEW FIELDS (v2.0) ==========
 
     # Workflow product-specific P&L
@@ -890,6 +901,10 @@ class ConsoleExecutionListener(BaseExecutionListener):
 
     async def on_workflow_pnl_update(self, event: WorkflowPnLEvent) -> None:
         """Print workflow P&L update for debugging"""
+        if event.workflow_pnl_rate is None or event.total_pnl_rate is None:
+            print(f"[{event.broker_node_id}] Workflow/account return unavailable "
+                  f"({event.monetary_unavailable_reason or 'missing monetary evidence'})")
+            return
         wf_pnl = float(event.workflow_pnl_rate)
         total_pnl = float(event.total_pnl_rate)
 

{programgarden_core-1.25.2 → programgarden_core-1.26.0}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 homepage = "https://programgarden.com"
 requires-python = ">=3.12"
 name = "programgarden-core"
-version = "1.25.2"
+version = "1.26.0"
 license = "AGPL-3.0-or-later"
 description = "ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의"
 readme = "README.md"