programgarden-core 1.25.3__tar.gz → 1.27.0__tar.gz

{programgarden_core-1.25.3 → programgarden_core-1.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 1.25.3
+Version: 1.27.0
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -113,3 +113,13 @@ 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.3 → programgarden_core-1.27.0}/README.md

@@ -97,3 +97,13 @@ monetary/rate scalars remain null when accounting evidence is unavailable.
 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.3 → programgarden_core-1.27.0}/programgarden_core/bases/listener.py

@@ -343,9 +343,18 @@ class WorkflowPnLEvent:
     monetary_status: Optional[str] = None
     monetary_basis: Optional[str] = None
     monetary_unavailable_reason: Optional[str] = None
+    # 워크플로우 **비율**을 못 낸 사유. 값을 비우는 것만으로는 "안 샀다" 와 "증권사가
+    # 평단·현재가를 안 보냈다" 가 구분되지 않는다 — 서버가 이 사유를 그대로 적재한다.
+    # 어휘: no_workflow_positions | basis_unreported | price_unreported | no_tracker |
+    #       computation_failed (dsl-api RATE_UNAVAILABLE_REASONS 와 공용).
+    # 🔴 monetary_* 를 재사용하지 않는다 — 그건 선물 전용 계약이고, 주식 이벤트에서
+    #    monetary_status is None 임을 고정하는 테스트가 있다.
+    workflow_rate_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) ==========
 
@@ -583,6 +592,67 @@ class RestartEvent:
     timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
 
+# ============================================================
+# 체결 확정 이벤트
+# ============================================================
+
+@dataclass
+class OrderFillEvent:
+    """
+    Event emitted when an order fill is confirmed and recorded to the ledger.
+
+    Facts only — no monetary computation. This mirrors what the broker reported
+    for one execution plus how the workflow ledger classified it. It fires once
+    per newly recorded fill, including a fill whose classification is only
+    resolved after the arrival-buffering timeout.
+
+    A fill whose ``classification`` is not "workflow" did not match one of our
+    recorded workflow orders, so ``node_id`` is None. Return/P&L interpretation
+    belongs to WorkflowPnLEvent and to broker-verified accounting, never to this
+    raw record — quantity/price are the reported execution facts, nothing is
+    summed or converted here.
+
+    Attributes:
+        job_id: Job identifier
+        node_id: OrderNode ID when this fill matches a recorded workflow order;
+            None for manual/unknown_api/other fills
+        order_no: Broker order number
+        order_date: Order date (YYYYMMDD)
+        execution_id: Broker execution identity when the frame reported one; else None
+        symbol: Symbol code
+        exchange: Exchange code
+        side: "buy" | "sell"
+        quantity: Filled quantity (reported, not aggregated)
+        price: Fill price (reported)
+        fill_time: Fill time (HHMMSSsss) as reported by the broker
+        product: "overseas_stock" | "overseas_futures" | "korea_stock"
+        provider: Broker provider (e.g. "ls")
+        classification: "workflow" | "manual" | "unknown_api" | "other"
+        commda_code: Broker communication-media code, preserved as reported
+        trading_mode: "live" | "paper"
+        received_at: ISO-8601 timestamp when the tracker received the fill
+        timestamp: Event emission timestamp
+    """
+    job_id: str
+    order_no: str
+    order_date: str
+    symbol: str
+    exchange: str
+    side: str  # "buy" | "sell"
+    quantity: Union[Decimal, float, int]
+    price: Union[Decimal, float]
+    fill_time: str
+    product: str
+    provider: str
+    classification: str  # "workflow" | "manual" | "unknown_api" | "other"
+    commda_code: str
+    trading_mode: str
+    received_at: str
+    node_id: Optional[str] = None
+    execution_id: Optional[Union[str, int]] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
 @runtime_checkable
 class ExecutionListener(Protocol):
     """
@@ -737,6 +807,21 @@ class ExecutionListener(Protocol):
         """
         ...
 
+    async def on_order_fill(self, event: 'OrderFillEvent') -> None:
+        """
+        Called when an order fill is confirmed and recorded to the ledger.
+
+        Facts only — no monetary computation. Fires once per newly recorded
+        fill, including a fill whose classification resolves after the
+        arrival-buffering timeout. Servers may durably record the fill (symbol,
+        side, quantity, price, classification) without trusting it as a return.
+
+        Args:
+            event: OrderFillEvent with order/execution identifiers, symbol,
+                side, quantity, price, classification, and trading mode.
+        """
+        ...
+
 
 class BaseExecutionListener:
     """
@@ -820,6 +905,10 @@ class BaseExecutionListener:
         """Default implementation: do nothing"""
         pass
 
+    async def on_order_fill(self, event: 'OrderFillEvent') -> None:
+        """Default implementation: do nothing"""
+        pass
+
 
 class ConsoleExecutionListener(BaseExecutionListener):
     """

{programgarden_core-1.25.3 → programgarden_core-1.27.0}/programgarden_core/nodes/base.py

@@ -361,6 +361,16 @@ OVERSEAS_FUTURES_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "pnl_amount", "type": "number", "description": "평가 손익 (금액)"},
     {"name": "pnl_rate", "type": "number", "description": "명목가 대비 수익률 (%) — 진입가/현재가로 산출 (승수 무관)"},
     {"name": "currency", "type": "string", "description": "통화 코드"},
+    # ── 손익 증거 메타 (v1.34.0 선물 monetary 작업에서 런타임에 추가됐는데 **선언이 안 따라왔다**) ──
+    # 선언에 없으면 `{{ nodes.account.positions[0].pnl_status }}` 같은 바인딩이
+    # INVALID_EXPRESSION_REF 로 **부당하게 거부된다** — 노드가 실제로 내보내는 값인데도.
+    # 이 값들이 있어야 "손익을 모른다" 와 "손익이 0" 을 사용자가 구분할 수 있다.
+    {"name": "pnl_status", "type": "string", "description": "손익 산출 가능 여부 (available / unavailable)"},
+    {"name": "pnl_basis", "type": "string", "description": "손익 산출 근거 (예: estimated_gross_price_change)"},
+    {"name": "pnl_currency", "type": "string", "description": "손익 금액의 통화 코드"},
+    {"name": "pnl_unavailable_reason", "type": "string", "description": "손익을 못 낸 사유 (pnl_status=unavailable 일 때)"},
+    {"name": "broker_pnl_amount", "type": "number", "description": "증권사가 보고한 평가손익 원문 (검증 전 값)"},
+    {"name": "broker_pnl_basis", "type": "string", "description": "증권사 보고 손익의 근거 표기 (예: broker_reported_unconfirmed)"},
 ]
 
 # ── 실시간 계좌 포지션 (RealAccountNode.positions) ──
@@ -416,6 +426,15 @@ OVERSEAS_FUTURES_REAL_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "pnl_rate", "type": "number", "description": "수익률 (%)"},
     {"name": "currency", "type": "string", "description": "통화 코드"},
     {"name": "product", "type": "string", "description": "상품 구분 (항상 overseas_futures)"},
+    # ── 손익 증거 메타 — REST 계좌(OVERSEAS_FUTURES_POSITION_FIELDS)와 **같은 세트**다.
+    # 두 노드가 같은 직렬화 헬퍼(`_serialize_futures_tracker_position`)를 쓰므로 선언도
+    # 어긋나면 안 된다. v1.34.0 에서 런타임만 늘고 선언이 안 따라와 바인딩이 거부됐다.
+    {"name": "pnl_status", "type": "string", "description": "손익 산출 가능 여부 (available / unavailable)"},
+    {"name": "pnl_basis", "type": "string", "description": "손익 산출 근거 (예: estimated_gross_price_change)"},
+    {"name": "pnl_currency", "type": "string", "description": "손익 금액의 통화 코드"},
+    {"name": "pnl_unavailable_reason", "type": "string", "description": "손익을 못 낸 사유 (pnl_status=unavailable 일 때)"},
+    {"name": "broker_pnl_amount", "type": "number", "description": "증권사가 보고한 평가손익 원문 (검증 전 값)"},
+    {"name": "broker_pnl_basis", "type": "string", "description": "증권사 보고 손익의 근거 표기 (예: broker_reported_unconfirmed)"},
 ]
 
 ORDER_RESULT_FIELDS: List[Dict[str, str]] = [

{programgarden_core-1.25.3 → programgarden_core-1.27.0}/pyproject.toml

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