programgarden-core 1.28.3__tar.gz → 1.30.0__tar.gz

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 1.28.3
+Version: 1.30.0
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -123,3 +123,11 @@ 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.
 
+## Workflow account boundary
+
+Each workflow allows one account and one product through at most one broker
+connection. Additional connections produce `DUPLICATE_BROKER_NODE`, including
+unbound or cross-product nodes. Reuse one broker for all consumers. Account-free
+workflows and unrelated credentials remain supported. See
+[the shared contract](../../docs/workflow_account_policy.md).
+

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/README.md

@@ -107,3 +107,11 @@ 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.
+
+## Workflow account boundary
+
+Each workflow allows one account and one product through at most one broker
+connection. Additional connections produce `DUPLICATE_BROKER_NODE`, including
+unbound or cross-product nodes. Reuse one broker for all consumers. Account-free
+workflows and unrelated credentials remain supported. See
+[the shared contract](../../docs/workflow_account_policy.md).

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/__init__.py

@@ -44,6 +44,7 @@ __all__ = [
     # Nodes - Broker (상품별 분리)
     "OverseasStockBrokerNode",
     "OverseasFuturesBrokerNode",
+    "OverseasFuturesOrderableQuantityNode",
     "KoreaStockBrokerNode",
     # Nodes - Market (해외주식)
     "OverseasStockMarketDataNode",

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/i18n/locales/en.json

@@ -1329,5 +1329,20 @@
   "fieldNames.FuturesContractNode.futures_exchange": "Exchange",
   "enums.contract_selection.front": "Front month (nearest expiry)",
   "enums.contract_selection.next": "Next month (roll target)",
-  "enums.contract_selection.quarterly": "Quarterly (Mar/Jun/Sep/Dec)"
+  "enums.contract_selection.quarterly": "Quarterly (Mar/Jun/Sep/Dec)",
+  "nodes.OverseasFuturesOrderableQuantityNode.name": "Futures Orderable Quantity",
+  "nodes.OverseasFuturesOrderableQuantityNode.description": "Reads contract-specific orderable quantity from the connected futures account. No order is submitted. Require verified=true and sufficient quantity before entry.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.symbol": "Contract",
+  "fields.OverseasFuturesOrderableQuantityNode.symbol": "Current contract identity: symbol and exchange.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.side": "Side",
+  "fields.OverseasFuturesOrderableQuantityNode.side": "Direction of the intended order.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.order_type": "Order Type",
+  "fields.OverseasFuturesOrderableQuantityNode.order_type": "Limit or market order capacity.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.price": "Order Price",
+  "fields.OverseasFuturesOrderableQuantityNode.price": "Observed proposed limit price; market queries use zero.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.query_type": "Query Type",
+  "fields.OverseasFuturesOrderableQuantityNode.query_type": "New positions, liquidation or total capacity.",
+  "enums.query_type.new": "New",
+  "enums.query_type.close": "Liquidation",
+  "enums.query_type.total": "Total"
 }

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/i18n/locales/ko.json

@@ -1329,5 +1329,20 @@
   "fieldNames.FuturesContractNode.futures_exchange": "거래소",
   "enums.contract_selection.front": "근월물 (만기 가장 가까움)",
   "enums.contract_selection.next": "차월물 (롤오버 대상)",
-  "enums.contract_selection.quarterly": "분기월물 (3·6·9·12월)"
+  "enums.contract_selection.quarterly": "분기월물 (3·6·9·12월)",
+  "nodes.OverseasFuturesOrderableQuantityNode.name": "해외선물 주문가능수량",
+  "nodes.OverseasFuturesOrderableQuantityNode.description": "연결된 해외선물 계좌에서 해당 종목의 주문가능수량을 조회합니다. 주문은 제출하지 않으며, 확인 성공 여부와 가능 수량을 확인한 뒤 진입합니다.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.symbol": "선물 종목",
+  "fields.OverseasFuturesOrderableQuantityNode.symbol": "현재 거래할 선물 종목과 거래소입니다.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.side": "매매 방향",
+  "fields.OverseasFuturesOrderableQuantityNode.side": "주문할 매수·매도 방향입니다.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.order_type": "주문 유형",
+  "fields.OverseasFuturesOrderableQuantityNode.order_type": "지정가 또는 시장가 주문가능수량을 확인합니다.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.price": "주문 가격",
+  "fields.OverseasFuturesOrderableQuantityNode.price": "현재 시세로 확인한 지정가입니다. 시장가는 0으로 조회합니다.",
+  "fieldNames.OverseasFuturesOrderableQuantityNode.query_type": "조회 구분",
+  "fields.OverseasFuturesOrderableQuantityNode.query_type": "신규 진입·청산·총 주문가능수량 중 조회할 항목입니다.",
+  "enums.query_type.new": "신규",
+  "enums.query_type.close": "청산",
+  "enums.query_type.total": "총가능"
 }

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/models/workflow.py

@@ -13,6 +13,44 @@ from programgarden_core.models.edge import Edge
 from programgarden_core.models.resource import ResourceLimits
 
 
+def validate_broker_connections(nodes: List[Dict[str, Any]]) -> List["ErrorInfo"]:
+    """Allow at most one account/product connection, including unbound brokers.
+
+    Inspect registered connection ports so aliases and custom broker node types
+    use the same rule. Reusing one connection through multiple edges is allowed;
+    account-free workflows and unrelated credential types remain unaffected.
+    """
+    from programgarden_core.registry import NodeTypeRegistry
+    from programgarden_core.models.validation import ErrorCode, ErrorLocation, build_error
+
+    registry = NodeTypeRegistry()
+    brokers = []
+    for node in nodes:
+        schema = registry.get_schema(node.get("type"))
+        if schema and any(port.get("type") == "broker_connection" for port in schema.outputs):
+            brokers.append(node)
+    if len(brokers) <= 1:
+        return []
+
+    broker_ids = [node.get("id") for node in brokers]
+    return [
+        build_error(
+            ErrorCode.DUPLICATE_BROKER_NODE,
+            "Duplicate broker connection: a workflow allows only one account and one product",
+            location=ErrorLocation(node_id=node.get("id"), node_type=node.get("type")),
+            suggestion=(
+                "Reuse the existing broker node for every consumer. Create a separate "
+                "workflow for another account or product; do not add another broker."
+            ),
+            details={
+                "existing": broker_ids[0], "duplicate": node.get("id"),
+                "broker_node_ids": broker_ids, "max_broker_connections": 1,
+            },
+        )
+        for node in brokers[1:]
+    ]
+
+
 class InputType(str, Enum):
     """워크플로우 입력 타입"""
 
@@ -220,7 +258,7 @@ class WorkflowDefinition(BaseModel):
             build_error,
         )
 
-        errors: List[ErrorInfo] = []
+        errors: List[ErrorInfo] = validate_broker_connections(self.nodes)
 
         # 1. Duplicate node IDs
         node_ids = self.get_node_ids()

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/nodes/__init__.py

@@ -44,6 +44,7 @@ from programgarden_core.nodes.account_stock import OverseasStockAccountNode
 from programgarden_core.nodes.account_futures import OverseasFuturesAccountNode
 from programgarden_core.nodes.open_orders_stock import OverseasStockOpenOrdersNode
 from programgarden_core.nodes.open_orders_futures import OverseasFuturesOpenOrdersNode
+from programgarden_core.nodes.orderable_quantity_futures import OverseasFuturesOrderableQuantityNode
 from programgarden_core.nodes.symbol_stock import OverseasStockSymbolQueryNode
 from programgarden_core.nodes.symbol_futures import OverseasFuturesSymbolQueryNode, FuturesContractNode
 # Data (상품 무관)
@@ -144,6 +145,7 @@ __all__ = [
     # Open Orders (미체결 주문 조회)
     "OverseasStockOpenOrdersNode",
     "OverseasFuturesOpenOrdersNode",
+    "OverseasFuturesOrderableQuantityNode",
     # Data (상품 무관)
     "SQLiteNode",
     "HTTPRequestNode",

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/nodes/broker.py

@@ -111,7 +111,7 @@ class OverseasStockBrokerNode(BaseBrokerNode):
         {
             "pattern": "Wiring a single broker across overseas_stock and overseas_futures nodes",
             "reason": "Product scope is a hard separator — overseas_futures nodes ignore stock-broker connections and the executor's auto-inject picks the wrong credential.",
-            "alternative": "Add OverseasFuturesBrokerNode in parallel; each product scope's nodes pick up its matching broker automatically.",
+            "alternative": "Use a separate workflow for overseas futures. Each workflow allows only one account and one product; reuse its existing broker node.",
         },
         {
             "pattern": "Omitting OverseasStockBrokerNode when using overseas_stock nodes",
@@ -207,7 +207,7 @@ class OverseasStockBrokerNode(BaseBrokerNode):
         ],
         "pitfalls": [
             "paper_trading must be false — overseas_stock has no LS-Sec paper trading channel",
-            "One workflow can have only one OverseasStockBrokerNode; duplicates compete for credential injection",
+            "A workflow allows at most one broker connection across all products and accounts, including unbound nodes; reuse that node for all consumers",
             "Credential type must be `broker_ls_overseas_stock` exactly; `broker_ls_overseas_futureoption` will not match",
         ],
     }
@@ -367,7 +367,7 @@ class OverseasFuturesBrokerNode(BaseBrokerNode):
         "pitfalls": [
             "Credential type must be `broker_ls_overseas_futureoption`",
             "paper_trading=True is not a full sandbox — some TRs still hit the real datafeed; always double-check order nodes before production",
-            "Each workflow holds exactly one futures broker; if you also trade stocks, add OverseasStockBrokerNode in parallel",
+            "Use one account and one product per workflow. Trade stocks in a separate workflow instead of adding a second broker",
         ],
     }
 
@@ -547,6 +547,7 @@ class KoreaStockBrokerNode(BaseBrokerNode):
         ],
         "pitfalls": [
             "Credential type must be `broker_ls_korea_stock` — overseas credentials will not match even though the fields are identical",
+            "Use one account and one product per workflow; reuse this broker for every domestic consumer instead of adding a second connection",
             "Every live order counts — always gate order nodes behind IfNode or ConditionNode when experimenting",
             "Use `dry_run=True` in ExecutionContext for sandbox runs (paper trading is not available at the LS-Sec level)",
         ],

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/nodes/data_futures.py

@@ -26,6 +26,11 @@ from programgarden_core.nodes.base import (
 )
 
 
+FUTURES_REST_PRICE_FIELDS = OVERSEAS_FUTURES_PRICE_DATA_FIELDS + [
+    {"name": "tick_size", "type": "number", "description": "Observed o3105 UntPrc quotation increment; null if unavailable."},
+]
+
+
 class OverseasFuturesMarketDataNode(BaseNode):
     """
     해외선물 REST API 시세 조회 노드 (단일 종목)
@@ -80,7 +85,7 @@ class OverseasFuturesMarketDataNode(BaseNode):
         ],
     }
     _features: ClassVar[List[str]] = [
-        "Returns a single futures contract's snapshot: symbol, exchange, symbol_name, price, change, change_pct, volume, open, high, low, close",
+        "Returns a futures contract snapshot including tick_size from observed o3105 UntPrc; missing tick size remains null",
         "Item-based execution: pair with SplitNode to query multiple contracts in sequence",
         "is_tool_enabled=True — AI Agent can call this node to look up live futures prices autonomously",
         "Supported exchanges: CME, EUREX, SGX, HKEX — symbol format includes contract month code (e.g., ESH26)",
@@ -168,6 +173,7 @@ class OverseasFuturesMarketDataNode(BaseNode):
         ),
         "output_consumption": (
             "Consume the `values` port ONLY — an array of {symbol, exchange, symbol_name, price, change, change_pct, volume, open, high, low, close}. "
+            "Each REST quote also includes tick_size from o3105 UntPrc; require a finite positive value before tick-dependent orders. "
             "⚠️ The `value` (singular) port is NOT populated at runtime — the executor emits `values` only; "
             "binding `{{ nodes.market.value }}` (or `.value.price`) silently resolves to None. "
             "TableDisplayNode.data ← `{{ nodes.market.values }}`; PositionSizingNode.market_data ← `{{ nodes.market.values }}`."
@@ -191,12 +197,12 @@ class OverseasFuturesMarketDataNode(BaseNode):
     ]
     _outputs: List[OutputPort] = [
         OutputPort(name="value", type="market_data", description="i18n:ports.market_data_value",
-                   fields=OVERSEAS_FUTURES_PRICE_DATA_FIELDS),
+                   fields=FUTURES_REST_PRICE_FIELDS),
         OutputPort(
             name="values",
             type="array",
             description="Array of per-contract market quotes — [{symbol, exchange, price, change, change_pct, ...}, ...]",
-            fields=OVERSEAS_FUTURES_PRICE_DATA_FIELDS,
+            fields=FUTURES_REST_PRICE_FIELDS,
         ),
     ]
 

programgarden_core-1.30.0/programgarden_core/nodes/orderable_quantity_futures.py

@@ -0,0 +1,60 @@
+"""Read contract-specific futures order capacity without submitting an order."""
+from typing import ClassVar, Dict, List, Literal, Optional
+
+from pydantic import Field
+
+from programgarden_core.nodes.base import BaseNode, BrokerProvider, InputPort, NodeCategory, OutputPort, ProductScope
+from programgarden_core.models.field_binding import ExpressionMode, FieldCategory, FieldSchema, FieldType
+
+
+class OverseasFuturesOrderableQuantityNode(BaseNode):
+    type: Literal["OverseasFuturesOrderableQuantityNode"] = "OverseasFuturesOrderableQuantityNode"
+    category: NodeCategory = NodeCategory.ACCOUNT
+    description: str = "i18n:nodes.OverseasFuturesOrderableQuantityNode.description"
+    _version: ClassVar[str] = "1.0.0"
+    _updated_at: ClassVar[str] = "2026-09-16"
+    _product_scope: ClassVar[ProductScope] = ProductScope.FUTURES
+    _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
+
+    symbol: Optional[Dict[str, str]] = Field(default=None, description="One current contract with symbol and exchange.")
+    side: Literal["buy", "sell"] = "buy"
+    order_type: Literal["limit", "market"] = "limit"
+    price: Optional[float] = Field(default=None, description="The intended limit order price; market queries use zero.")
+    query_type: Literal["new", "close", "total"] = "new"
+
+    _inputs: List[InputPort] = [InputPort(name="trigger", type="signal", required=False)]
+    _outputs: List[OutputPort] = [
+        OutputPort(name="quantity", type="number", description="Observed orderable contracts; null if unavailable."),
+        OutputPort(name="verified", type="boolean", description="True only for a complete matching broker response."),
+        OutputPort(name="error", type="string", description="Reason the quantity is unavailable; null for a valid zero or positive result."),
+    ]
+    _usage: ClassVar[dict] = {
+        "when_to_use": ["Check contract-specific capacity before a futures order; connect the current quote first."],
+        "when_not_to_use": ["Stock affordability, account performance, or proof of an accepted/filled order."],
+        "typical_scenarios": ["FuturesContractNode → market.values → matching quote → orderable quantity → entry guard → order."],
+    }
+    _features: ClassVar[list] = [
+        "Queries CIDBQ01400 using the actual contract, side, order type and price.",
+        "Uses the same broker account as the workflow; never submits an order.",
+        "Zero capacity is a normal result. Missing, partial or mismatched responses remain unavailable.",
+        "Deep validation uses an offline fixture and does not prove real account capacity.",
+    ]
+    _node_guide: ClassVar[dict] = {
+        "input_handling": "Bind symbol as a full {symbol, exchange} object from the runtime contract and price from the matching current quote. Put an ordering edge from every producer. Use query_type=new only for new positions, close for liquidation, total only when explicitly intended.",
+        "output_consumption": "Require verified=true and quantity >= the intended contract count. Also verify holdings, pending orders, price/tick validity and their identities. Never replace unknown capacity with zero or compare a quoted futures price to cash as a margin check.",
+        "pitfalls": ["Capacity is a snapshot, not a reservation or an order guarantee. ACK and actual fills require separate evidence."],
+    }
+
+    @classmethod
+    def is_tool_enabled(cls) -> bool:
+        return True
+
+    @classmethod
+    def get_field_schema(cls) -> Dict[str, FieldSchema]:
+        return {
+            "symbol": FieldSchema(name="symbol", type=FieldType.OBJECT, description="Current contract identity.", category=FieldCategory.PARAMETERS, expression_mode=ExpressionMode.BOTH, required=True, object_schema=[{"name":"symbol","type":"STRING","required":True},{"name":"exchange","type":"STRING","required":True}]),
+            "side": FieldSchema(name="side", type=FieldType.ENUM, enum_values=["buy","sell"], default="buy", category=FieldCategory.PARAMETERS, expression_mode=ExpressionMode.BOTH),
+            "order_type": FieldSchema(name="order_type", type=FieldType.ENUM, enum_values=["limit","market"], default="limit", category=FieldCategory.PARAMETERS, expression_mode=ExpressionMode.BOTH),
+            "price": FieldSchema(name="price", type=FieldType.NUMBER, description="Proposed order price in the contract's quotation units.", category=FieldCategory.PARAMETERS, expression_mode=ExpressionMode.BOTH),
+            "query_type": FieldSchema(name="query_type", type=FieldType.ENUM, enum_values=["new","close","total"], default="new", category=FieldCategory.PARAMETERS, expression_mode=ExpressionMode.BOTH),
+        }

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/programgarden_core/registry/node_registry.py

@@ -164,7 +164,7 @@ class NodeTypeRegistry:
             # Account - Futures (해외선물)
             OverseasFuturesAccountNode, OverseasFuturesRealAccountNode, OverseasFuturesRealOrderEventNode,
             # Open Orders (미체결 조회)
-            OverseasStockOpenOrdersNode, OverseasFuturesOpenOrdersNode,
+            OverseasStockOpenOrdersNode, OverseasFuturesOpenOrdersNode, OverseasFuturesOrderableQuantityNode,
             # Korea Stock (국내주식)
             KoreaStockBrokerNode,
             KoreaStockAccountNode, KoreaStockOpenOrdersNode,
@@ -212,7 +212,7 @@ class NodeTypeRegistry:
             # Account - Futures (해외선물)
             OverseasFuturesAccountNode, OverseasFuturesRealAccountNode, OverseasFuturesRealOrderEventNode,
             # Open Orders (미체결 조회)
-            OverseasStockOpenOrdersNode, OverseasFuturesOpenOrdersNode,
+            OverseasStockOpenOrdersNode, OverseasFuturesOpenOrdersNode, OverseasFuturesOrderableQuantityNode,
             # Korea Stock (국내주식)
             KoreaStockBrokerNode,
             KoreaStockAccountNode, KoreaStockOpenOrdersNode,

{programgarden_core-1.28.3 → programgarden_core-1.30.0}/pyproject.toml

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