programgarden-core 2.0.1__tar.gz → 2.2.0__tar.gz

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.0.1
+Version: 2.2.0
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/code_node.py

@@ -104,9 +104,11 @@ FORBIDDEN_ATTR_NAMES: frozenset = frozenset({
 })
 
 # ── Denylist: introspection-escape / exfiltration dunders & frame attrs ──────
-# NOTE: enforcement is the BLANKET underscore rule in _scan_ast (any attribute
-# or string beginning with '_' is rejected), which subsumes every dunder. This
-# explicit set is retained for documentation / message clarity.
+# NOTE: enforcement is the underscore rule in _scan_ast — any ATTRIBUTE beginning
+# with '_' is rejected (subsumes every dunder and private module re-export like
+# random._os); STRING literals are rejected when they contain a dunder or name a
+# blocked attribute re-export (bare single-underscore data-key strings such as
+# "_partial_failure" are allowed). This explicit set is retained for message clarity.
 FORBIDDEN_DUNDERS: frozenset = frozenset({
     "__class__", "__bases__", "__base__", "__subclasses__", "__mro__",
     "__globals__", "__code__", "__closure__", "__func__", "__self__",
@@ -224,12 +226,18 @@ def _scan_ast(tree: ast.AST, allowed_imports: Set[str]) -> List[Dict[str, Any]]:
         elif isinstance(node, ast.Constant) and isinstance(node.value, str):
             v = node.value
             bad = None
-            if v.startswith("_"):
-                bad = f"string literal '{v}' begins with '_' (introspection escape)"
-            elif "__" in v:
-                bad = f"string literal contains a dunder (introspection escape)"
-            elif v in FORBIDDEN_ATTR_NAMES:
-                bad = f"string literal '{v}' names a blocked attribute"
+            # A single leading underscore names a documented native data marker
+            # read as a dict key (e.g. balance["_partial_failure"], "_source"),
+            # so it is allowed. Still rejected: dunder-style names, and blocked
+            # public/underscored attribute re-exports ("os"/"sys"/"system"/"_os"/
+            # "_sys"... -> in FORBIDDEN_ATTR_NAMES via lstrip("_")), and attribute-
+            # walking format fields. getattr/attrgetter/operator/format are
+            # independently blocked, so a bare underscore data-key string cannot
+            # be turned into attribute access.
+            if "__" in v:
+                bad = "string literal contains a dunder (introspection escape)"
+            elif v.lstrip("_") in FORBIDDEN_ATTR_NAMES:
+                bad = f"string literal '{v}' names a blocked attribute (introspection escape)"
             elif _FORMAT_ATTR_RE.search(v):
                 bad = "format string performs attribute access (introspection escape)"
             if bad:

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/expression/evaluator.py

@@ -56,6 +56,8 @@ def _get_nested_value(obj: Any, path: str) -> Any:
             return None
         if isinstance(current, dict):
             current = current.get(key)
+        elif isinstance(current, NodeOutputProxy) and isinstance(current._data, dict) and key in current._data:
+            current = current._data[key]  # port before helper method (see _eval_node)
         else:
             current = getattr(current, key, None)
     return current
@@ -941,6 +943,15 @@ class SafeEvaluator:
             obj = self._eval_node(node.value)
             if isinstance(obj, dict):
                 return obj.get(node.attr)
+            # An output PORT wins over a proxy helper of the same name: a node
+            # whose port is called `count` (OpenOrdersNode), `sum`, `first`, `last`,
+            # `map` or `filter` must resolve to the port value, not to the bound
+            # helper method (observed 2026-09-24: `{{ nodes.open_orders.count }}`
+            # returned `NodeOutputProxy.count` and the CodeNode input could not be
+            # serialized — "Object of type method is not JSON serializable").
+            if isinstance(obj, NodeOutputProxy) and isinstance(obj._data, dict) and node.attr in obj._data:
+                value = obj._data[node.attr]
+                return NodeOutputProxy(value) if isinstance(value, list) else value
             return getattr(obj, node.attr, None)
 
         # 인덱싱 (arr[0], dict["key"])
@@ -952,6 +963,15 @@ class SafeEvaluator:
         # 함수 호출
         if isinstance(node, ast.Call):
             func = self._eval_node(node.func)
+            if not callable(func) and isinstance(node.func, ast.Attribute):
+                # `{{ nodes.open_orders.count() }}`: the bare attribute resolves to
+                # the `count` PORT (see the Attribute branch), but a CALL of that
+                # name still means the proxy helper, so workflows written against
+                # the helper keep working on nodes that also declare the port.
+                owner = self._eval_node(node.func.value)
+                helper = getattr(owner, node.func.attr, None) if isinstance(owner, NodeOutputProxy) else None
+                if callable(helper):
+                    func = helper
             if not callable(func):
                 raise ExpressionError(f"호출 불가능한 객체: {func}")
             args = [self._eval_node(arg) for arg in node.args]

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/i18n/locales/en.json

@@ -291,7 +291,7 @@
   "fields.CurrencyRateNode.target_currencies": "Target currencies. Select currencies to get exchange rates against the base currency.",
   "fields.CurrencyRateNode.timeout_seconds": "API request timeout (seconds). Default 30s, adjust based on your network conditions.",
   "fields.CodeNode.code": "Python source that defines async def execute(data, params, context). Sandboxed: only pure-computation stdlib imports (math, statistics, json, datetime, ...) are allowed; no credentials, network, filesystem, or introspection.",
-  "fields.CodeNode.outputs": "Output port declarations [{name, type}]. Leave empty for a single 'result' port carrying the whole return value. Declared ports are consumed downstream by {{ nodes.<id>.<port> }} expressions written into a consumer's generic input field (TableDisplayNode.data, IfNode.left/right, ...), not by typed-port matching; declaring them enables static typo-guarding.",
+  "fields.CodeNode.outputs": "Output port declarations [{name, type}]. Leave empty for a single 'result' port carrying the whole return value: return 3 yields result=3; return {'result':3} yields result={'result':3}. Declare [{name:'result',type:'number'}] to map a returned dict's result key to the number port. Declared ports are consumed downstream by {{ nodes.<id>.<port> }} expressions written into a consumer's generic input field (TableDisplayNode.data, IfNode.left/right, ...), not by typed-port matching; declaring them enables static typo-guarding.",
   "fields.CodeNode.params": "Parameters passed to execute() as `params`. Expression bindings are allowed (e.g. a period or threshold).",
   "fields.CodeNode.data": "Input data passed to execute() as `data`. Bind the whole upstream value (e.g. {{ nodes.hist.values }}) and loop over it inside the function.",
   "fields.FieldMappingNode.data": "Input data to transform. Bind from HTTPRequestNode response or other node outputs.",

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/i18n/locales/ko.json

@@ -291,7 +291,7 @@
   "fields.CurrencyRateNode.target_currencies": "대상 통화 목록. 기준 통화 대비 환율을 조회할 통화를 선택하세요.",
   "fields.CurrencyRateNode.timeout_seconds": "API 요청 타임아웃 (초). 기본 30초, 네트워크 환경에 따라 조정하세요.",
   "fields.CodeNode.code": "async def execute(data, params, context) 를 정의하는 파이썬 소스. 샌드박스: 순수 계산용 표준 라이브러리(math, statistics, json, datetime, ...) import 만 허용, credential·네트워크·파일시스템·introspection 불가.",
-  "fields.CodeNode.outputs": "출력 포트 선언 [{name, type}]. 비워두면 반환값 전체를 담는 단일 'result' 포트가 됩니다. 선언한 포트는 소비자 노드의 범용 입력 필드(TableDisplayNode.data, IfNode.left/right 등)에 {{ nodes.<id>.<port> }} 표현식으로 소비됩니다 — 타입드 포트 매칭이 아니라 이름으로 dict 키를 꺼내는 방식. 선언하면 정적 오타 검증이 적용됩니다.",
+  "fields.CodeNode.outputs": "출력 포트 선언 [{name, type}]. 비워두면 반환값 전체를 담는 단일 'result' 포트가 됩니다. 선언한 포트는 소비자 노드의 범용 입력 필드(TableDisplayNode.data, IfNode.left/right 등)에 {{ nodes.<id>.<port> }} 표현식으로 소비됩니다 — 타입드 포트 매칭이 아니라 이름으로 dict 키를 꺼내는 방식. 선언하면 정적 오타 검증이 적용됩니다. outputs를 비우면 반환값 전체가 result입니다. return 3은 result=3, return {'result':3}은 result={'result':3}이 됩니다. 반환 딕셔너리의 result 키를 숫자 포트로 사용하려면 outputs에 name:result, type:number를 선언하세요.",
   "fields.CodeNode.params": "execute() 에 `params` 로 전달되는 파라미터. 표현식 바인딩 허용(예: 기간·임계값).",
   "fields.CodeNode.data": "execute() 에 `data` 로 전달되는 입력 데이터. 상류 값 전체를 바인딩(예: {{ nodes.hist.values }})하고 함수 안에서 반복하세요.",
   "fields.FieldMappingNode.data": "변환할 입력 데이터. HTTPRequestNode 응답이나 다른 노드 출력을 바인딩하세요.",

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/account_futures.py

@@ -65,6 +65,12 @@ class OverseasFuturesAccountNode(BaseNode):
         "Returns three ports: held_symbols (symbol list), balance (margin/equity summary), positions (per-contract P&L)",
         "is_tool_enabled=True — AI Agent can call this node as a tool to inspect futures portfolio state",
         "One-shot REST call; supports paper_trading mode via OverseasFuturesBrokerNode",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "Its recording (held_symbols, balance, positions) is what the workflow's guard reads; the replay's simulated ledger is seeded only from fixture.broker.account, and a holding used by a scenario must appear in both with the same integer quantity",
+        "A frame that submits no order must expect exactly the seeded cash and positions; an insufficient_cash case needs both the seeded cash and the recorded orderable_amount below quantity times the quoted price",
+        "Retained across realtime events (queried once at startup); re-runs on every schedule tick",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/account_korea_stock.py

@@ -64,6 +64,12 @@ class KoreaStockAccountNode(BaseNode):
         "Returns three ports: held_symbols (symbol list with KRX codes), balance (KRW cash/equity summary), positions (per-symbol P&L in KRW)",
         "is_tool_enabled=True — AI Agent can call this node as a tool to inspect Korea stock portfolio state",
         "Real trading only (KoreaStockBrokerNode does not support paper_trading mode); no mock data",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "Its recording (held_symbols, balance, positions) is what the workflow's guard reads; the replay's simulated ledger is seeded only from fixture.broker.account, and a holding used by a scenario must appear in both with the same integer quantity",
+        "A frame that submits no order must expect exactly the seeded cash and positions; an insufficient_cash case needs both the seeded cash and the recorded orderable_amount below quantity times the quoted price",
+        "Retained across realtime events (queried once at startup); re-runs on every schedule tick",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -111,7 +117,7 @@ class KoreaStockAccountNode(BaseNode):
                     }
                 ],
             },
-            "expected_output": "positions port: list of {symbol, quantity, avg_price, pnl_rate} in KRW; balance port: {cash_krw, total_eval_krw, orderable_amount}; held_symbols: [{symbol}].",
+            "expected_output": "positions: observed holdings with symbol, quantity, avg_price, pnl_rate and cost/P&L availability; missing money stays null. balance: {deposit, total_eval, orderable_amount} in KRW; held_symbols: [{exchange, symbol}].",
         },
         {
             "title": "Cash check before Korea stock order",

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/account_stock.py

@@ -66,6 +66,12 @@ class OverseasStockAccountNode(BaseNode):
         "Returns three ports: held_symbols (symbol list), balance (cash/equity summary), positions (per-symbol P&L)",
         "is_tool_enabled=True — AI Agent can call this node as a tool to inspect portfolio state",
         "One-shot REST call: safe to use in scheduled or on-demand workflows without WebSocket overhead",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "Its recording (held_symbols, balance, positions) is what the workflow's guard reads; the replay's simulated ledger is seeded only from fixture.broker.account, and a holding used by a scenario must appear in both with the same integer quantity",
+        "A frame that submits no order must expect exactly the seeded cash and positions; an insufficient_cash case needs both the seeded cash and the recorded orderable_amount below quantity times the quoted price",
+        "Retained across realtime events (queried once at startup); re-runs on every schedule tick",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/backtest_futures.py

@@ -102,6 +102,13 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
         "adjust=True applies roll-adjusted prices for continuous contract backtesting",
         "is_tool_enabled=True — AI Agent can fetch futures history for technical analysis autonomously",
         "Item-based execution: pair with SplitNode to fetch OHLCV for multiple contracts",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "The value port is one row object whose time_series lists bars of exactly {date, open, high, low, close, volume}; the values port is the array of such rows",
+        "This ohlcv_data is not the realtime shape: a *RealMarketDataNode records ohlcv_data as a symbol-keyed object of bar lists, although both are typed ohlcv_data",
+        "A previous close is the close of the corresponding bar in time_series; a change cannot be computed from a single bar",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/backtest_korea_stock.py

@@ -102,6 +102,13 @@ class KoreaStockHistoricalDataNode(BaseNode):
         "start_date / end_date accept YYYYMMDD strings or `{{ date.ago(N, format='yyyymmdd') }}` expressions",
         "is_tool_enabled=True — AI Agent can fetch domestic historical data for fundamental/technical analysis",
         "Symbol format: 6-digit KRX code (e.g., '005930') without exchange field",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "The value port is one row object whose time_series lists bars of exactly {date, open, high, low, close, volume}; the values port is the array of such rows",
+        "This ohlcv_data is not the realtime shape: a *RealMarketDataNode records ohlcv_data as a symbol-keyed object of bar lists, although both are typed ohlcv_data",
+        "A previous close is the close of the corresponding bar in time_series; a change cannot be computed from a single bar",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/backtest_stock.py

@@ -102,6 +102,13 @@ class OverseasStockHistoricalDataNode(BaseNode):
         "adjust=True applies split/dividend-adjusted prices for accurate long-term backtesting",
         "is_tool_enabled=True — AI Agent can fetch historical data autonomously for technical analysis",
         "Item-based execution: pair with SplitNode to fetch history for each symbol in a watchlist",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "The value port is one row object whose time_series lists bars of exactly {date, open, high, low, close, volume}; the values port is the array of such rows",
+        "This ohlcv_data is not the realtime shape: a *RealMarketDataNode records ohlcv_data as a symbol-keyed object of bar lists, although both are typed ohlcv_data",
+        "A previous close is the close of the corresponding bar in time_series; a change cannot be computed from a single bar",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/base.py

@@ -328,7 +328,7 @@ OVERSEAS_STOCK_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "market", "type": "string", "description": "시장 구분명"},
 ]
 
-# 국내주식 REST 계좌 (t0424)
+# Domestic REST account: observed CSPAQ12300 evidence plus executor aliases.
 KOREA_STOCK_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "exchange", "type": "string", "description": "거래소 코드 (항상 KRX)"},
     {"name": "symbol", "type": "string", "description": "종목코드"},
@@ -342,6 +342,20 @@ KOREA_STOCK_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "sellable_qty", "type": "number", "description": "매도 가능 수량"},
     {"name": "eval_amount", "type": "number", "description": "평가 금액"},
     {"name": "product", "type": "string", "description": "상품 구분 (항상 korea_stock)"},
+    {"name": "symbol_name", "type": "string", "description": "Observed instrument name; name alias uses the same value"},
+    {"name": "currency", "type": "string", "description": "Valuation currency: KRW"},
+    {"name": "buy_price", "type": "number", "description": "Observed average acquisition price; null when unavailable"},
+    {"name": "average_price", "type": "number", "description": "Observed average acquisition price; null when unavailable"},
+    {"name": "acquisition_amount", "type": "number", "description": "Observed acquisition amount; null when unavailable"},
+    {"name": "purchase_amount", "type": "number", "description": "Acquisition amount alias; null when unavailable"},
+    {"name": "pnl_rate_basis", "type": "string", "description": "Broker average cost basis, commission excluded"},
+    {"name": "pnl_rate_status", "type": "string", "description": "available or unavailable; missing evidence is not zero return"},
+    {"name": "pnl_status", "type": "string", "description": "available or unavailable"},
+    {"name": "pnl_unavailable_reason", "type": "string", "description": "Missing P&L evidence reason; null when available"},
+    {"name": "cost_basis", "type": "string", "description": "Broker average cost basis, commission excluded"},
+    {"name": "cost_status", "type": "string", "description": "available or unavailable"},
+    {"name": "cost_unavailable_reason", "type": "string", "description": "Missing acquisition evidence reason; null when available"},
+    {"name": "observed_at", "type": "string", "description": "UTC ISO observation timestamp"},
 ]
 
 # 해외선물 REST 계좌 (CIDBQ01500 block2)
@@ -1030,4 +1044,4 @@ class BaseMessagingNode(BaseNode):
                 category=FieldCategory.SETTINGS,
                 depends_on={"resilience.fallback.mode": "default_value"},
             ),
-        }
+        }

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/broker.py

@@ -101,6 +101,10 @@ class OverseasStockBrokerNode(BaseBrokerNode):
         "Creates and caches the LS-Sec session so every downstream overseas_stock node shares the same login",
         "`connection` output is auto-injected into every overseas_stock node by the executor — no manual binding required",
         "credential_types=['broker_ls_overseas_stock'] ensures only the correct credential is selected",
+        "On the first run its recording's request carries no connection; its output is {\"connection\": {provider, product, paper_trading, broker_node_id, and credential_id only when the account is linked}}, and an unlinked account has no credential_id key (never null)",
+        "On a schedule tick the executor injects this broker's own retained output.connection into its request, so a broker tick recording must repeat that connection or the replay refuses it",
+        "Downstream product-scoped nodes reference it by request.connection.broker_node_id set to this node's id; the compiler completes provider/product/paper_trading (and credential_id) from this broker's recorded output.connection",
+        "paper_trading must be false; the executor raises if it is true",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -295,6 +299,9 @@ class OverseasFuturesBrokerNode(BaseBrokerNode):
         "Only broker that natively supports LS-Sec paper trading (set paper_trading=True)",
         "Auto-injects the connection into every overseas_futures node in the same workflow",
         "credential_types=['broker_ls_overseas_futures'] keeps the selector scoped",
+        "On the first run its recording's request carries no connection; its output is {\"connection\": {provider, product, paper_trading, broker_node_id, and credential_id only when the account is linked}}, and an unlinked account has no credential_id key (never null)",
+        "On a schedule tick the executor injects this broker's own retained output.connection into its request, so a broker tick recording must repeat that connection or the replay refuses it",
+        "Downstream product-scoped nodes reference it by request.connection.broker_node_id set to this node's id; the compiler completes provider/product/paper_trading (and credential_id) from this broker's recorded output.connection",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -455,6 +462,9 @@ class KoreaStockBrokerNode(BaseBrokerNode):
         "Dedicated credential type `broker_ls_korea_stock` keeps KRX credentials isolated from overseas ones",
         "Auto-injects connection into every korea_stock scoped node",
         "Executes the Korean-specific workflow P&L tracker (KRW-denominated) when account nodes are wired",
+        "On the first run its recording's request carries no connection; its output is {\"connection\": {provider, product, paper_trading, broker_node_id, and credential_id only when the account is linked}}, and an unlinked account has no credential_id key (never null)",
+        "On a schedule tick the executor injects this broker's own retained output.connection into its request, so a broker tick recording must repeat that connection or the replay refuses it",
+        "Downstream product-scoped nodes reference it by request.connection.broker_node_id set to this node's id; the compiler completes provider/product/paper_trading (and credential_id) from this broker's recorded output.connection",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/code.py

@@ -69,8 +69,10 @@ class CodeNode(BaseNode):
     - `context` = a READ-ONLY scrubbed context: safe helper namespaces
       (`context.date/finance/stats/format/lst`), a risk-tracker read snapshot,
       and workflow meta. It exposes NO credentials, broker, or executor.
-    - Return a dict; its keys map to the declared `outputs` ports. If `outputs`
-      is omitted, the entire return value is exposed on a single `result` port.
+    - With declared `outputs`, return a dict keyed by those ports. A single
+      declared port also accepts a scalar. With no declaration, the WHOLE return
+      value becomes `result`: return 3 gives result=3; return {'result': 3}
+      gives result={'result': 3}, not result=3.
 
     Example DSL:
         {
@@ -108,9 +110,15 @@ class CodeNode(BaseNode):
     outputs: List[Dict[str, str]] = Field(
         default_factory=list,
         description=(
-            "Output port declarations [{name, type}]. Empty → single 'result' port. "
+            "Output port declarations [{name, type}]. Empty exposes the WHOLE return on result: "
+            "return 3 gives result=3; return {'result': 3} gives result={'result': 3}. "
+            "With outputs=[{name:'result',type:'number'}], return {'result':3} gives result=3. "
             "Declared ports are consumed downstream by {{ nodes.<id>.<port> }} expressions, "
-            "not by typed-port matching; declaring them enables static typo-guarding."
+            "not by typed-port matching; declaring them enables static typo-guarding. "
+            "Do NOT name a port 'error' or 'reason': the engine treats a top-level 'error' "
+            "value (and a top-level 'reason' of no_symbol/no_price/invalid_input) as a node "
+            "failure, so such a port makes a successful return read as an engine error. Put "
+            "any status/diagnostic under a differently named port or nested object instead."
         ),
     )
 
@@ -160,6 +168,9 @@ class CodeNode(BaseNode):
         "Safe helper namespaces available on context (date/finance/stats/format/lst) mirror expression bindings",
         "Batch-friendly: receives the whole upstream array in `data` (one subprocess call, loop in-code)",
         "Multi-upstream: accepts any number of upstream producers — bind each one to its own expression-bound `params` key ({{ nodes.<id>.<port> }}) and read it with params.get(...)",
+        "The top-level output keys error (truthy) and reason in {no_symbol, no_price, invalid_input} are engine failure markers; never declare or expect them as ports — put a diagnostic inside a nested object port (e.g. result.error) or a differently named port",
+        "A computation node: it receives no external recording in a suite (its code runs) and keeps no state across ticks; a durable one-shot guard needs ThrottleNode or SQLiteNode",
+        "Completing with a boolean false does not gate a downstream order node; route the boolean through an IfNode true edge",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -174,9 +185,14 @@ class CodeNode(BaseNode):
         },
         {
             "pattern": "Declaring 'outputs' ports whose names the return dict never sets",
-            "reason": "A declared port missing from the return maps to None with a warning — a silent-looking gap downstream.",
+            "reason": "Deep/replay validation rejects missing declared ports and values that violate their declared types. Legacy live mapping to None is not evidence of a valid output.",
             "alternative": "Return a dict whose keys exactly match every declared output port name.",
         },
+        {
+            "pattern": "Naming a declared output port 'error' or 'reason'",
+            "reason": "The engine (live runtime and replay) treats a top-level 'error' value, and a top-level 'reason' of no_symbol/no_price/invalid_input, as a node failure. A port with either name makes the node's own successful output read as an engine execution error, and no calculation defect exists to repair.",
+            "alternative": "Rename the port (e.g. 'status', 'note', 'detail') or nest status inside another object such as {'result': {...}}; keep 'error'/'reason' out of the top-level return.",
+        },
         {
             "pattern": "Feeding a CodeNode return of non-standard shape into a typed node (order node, ConditionNode)",
             "reason": "The binding layer checks port existence but never coerces shape; a wrong shape does not fail at the CodeNode — it fails downstream where the typed node reads it (e.g. order nodes expect the Symbol Data Format array of {symbol, exchange, ...}).",
@@ -347,7 +363,7 @@ class CodeNode(BaseNode):
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
         "input_handling": "SINGLE upstream: bind the whole upstream value to 'data' (e.g. \"{{ nodes.hist.values }}\") and loop over it inside execute() — CodeNode is not per-item auto-iterated. MULTIPLE upstreams (2+ producers feeding this node — fully supported): 'data' holds ONE whole value, so do NOT try to merge producers into it. Keep an edge from EACH producer and bind EACH upstream value to its own key under 'params' — params values are expression-bindable: \"params\": {\"fgi_value\": \"{{ nodes.fgi.value }}\", \"vix_response\": \"{{ nodes.vix_http.response }}\"} — then read them with params.get('fgi_value', 50) inside execute(). params.get(...) is the normal, always-allowed way to read bound inputs. 'params' also carries fixed knobs (literals). Declare 'outputs' when you want named ports; omit it to use the single 'result' port.",
-        "output_consumption": "Downstream nodes do NOT need a matching typed port. They consume a CodeNode output by writing a {{ nodes.<id>.<port> }} expression into their own generic input field (e.g. TableDisplayNode.data, IfNode.left/right, FieldMappingNode.data) — the binding layer resolves the dict key by name, it does not type-match ports. With no outputs declared, read {{ nodes.<id>.result }} (the whole return value). A declared output port that no node references is fine; a declared port absent from the return dict resolves to None with a warning. Because ports are declared, validate() typo-guards these references.",
+        "output_consumption": "Downstream nodes do NOT need a matching typed port. They consume a CodeNode output by writing a {{ nodes.<id>.<port> }} expression into their own generic input field (e.g. TableDisplayNode.data, IfNode.left/right, FieldMappingNode.data) — the binding layer resolves the dict key by name, it does not type-match ports. With no outputs declared, read {{ nodes.<id>.result }} (the whole return value). A declared output port that no node references is fine; a declared port absent from the return dict fails deep/replay validation. Do not rely on legacy live None substitution. Because ports are declared, validate() typo-guards these references.",
         "common_combinations": [
             "CodeNode → TableDisplayNode / LineChartNode / TelegramNode (display or sink — any return shape works)",
             "CodeNode → OverseasStockNewOrderNode / ConditionNode (typed node — return the standard [{symbol, exchange, ...}] shape)",
@@ -362,7 +378,7 @@ class CodeNode(BaseNode):
             "sandbox, and I/O/system stdlib (os, sys, socket, subprocess, urllib, http, requests, open) is "
             "blocked. Re-implement such functionality by hand in pure Python using the allowed stdlib.",
             "No credential/broker/network access — CodeNode cannot place orders or fetch data itself; feed it data from typed nodes.",
-            "Declared output ports must all appear as keys in the returned dict, or they resolve to None.",
+            "Every declared output must be present and match its type in deep/replay validation. A single declared port also supports a scalar return.",
             "There is NO one-upstream limit. Only the `data` field carries a single whole value — "
             "the node accepts any number of upstream producers. With 2+ producers, keep an edge "
             "from each and bind each value to its own `params` key "
@@ -440,7 +456,7 @@ class CodeNode(BaseNode):
                 expression_mode=ExpressionMode.FIXED_ONLY,
                 category=FieldCategory.PARAMETERS,
                 ui_component=UIComponent.CUSTOM_CODE_EDITOR,
-                example="async def execute(data, params, context):\n    return {'result': data}",
+                example="async def execute(data, params, context):\n    return data",
                 expected_type="str",
                 help_text=(
                     "Define async def execute(data, params, context). Sandboxed: no "

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/data.py

@@ -176,6 +176,10 @@ class SQLiteNode(BaseNode):
         "Outputs rows (list), affected_count (int), and last_insert_id (int) to cover all read/write patterns",
         "is_tool_enabled=True — AI Agent can use SQLiteNode as a tool to read or write local state",
         "Databases are scoped to /app/data/ directory; db_name selects the file",
+        "Has a dedicated replay adapter (execute_sqlite) and takes no external recording; it runs against a file-backed database rooted at the run's storage directory",
+        "State written on one tick or event frame persists to that database and stays visible on later frames within the run, so a durable duplicate guard can be built on it",
+        "Each execution runs exactly ONE SQL statement (execute_query and every simple-mode action call db.execute once); 'CREATE TABLE …; INSERT …' in one query fails with 'You can only execute one statement at a time'",
+        "Neither mode creates a table: an insert/select into a missing table fails with 'no such table'; create it first with a separate execute_query SQLiteNode (CREATE TABLE IF NOT EXISTS …) placed upstream, then read/write it here",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -212,7 +216,7 @@ class SQLiteNode(BaseNode):
                         "operation": "simple",
                         "table": "hwm",
                         "action": "upsert",
-                        "values": {"symbol": "{{ nodes.market.value.symbol }}", "peak": '{{ nodes.market.value.price }}'},
+                        "values": {"symbol": "{{ nodes.market.values[0].symbol }}", "peak": '{{ nodes.market.values[0].price }}'},
                         "on_conflict": "symbol",
                     },
                     {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/data_futures.py

@@ -90,6 +90,11 @@ class OverseasFuturesMarketDataNode(BaseNode):
         "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)",
         "Broker connection is auto-injected via DAG traversal from OverseasFuturesBrokerNode",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "In replay the one-shot quote records its `values` port as a flat row list at nodes.<id>.output.values; this is not the realtime symbol-keyed ohlcv_data shape",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -196,8 +201,6 @@ class OverseasFuturesMarketDataNode(BaseNode):
         InputPort(name="trigger", type="signal", description="i18n:ports.trigger", required=False),
     ]
     _outputs: List[OutputPort] = [
-        OutputPort(name="value", type="market_data", description="i18n:ports.market_data_value",
-                   fields=FUTURES_REST_PRICE_FIELDS),
         OutputPort(
             name="values",
             type="array",
@@ -206,9 +209,9 @@ class OverseasFuturesMarketDataNode(BaseNode):
         ),
     ]
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.0.1"
+    _updated_at: ClassVar[str] = "2026-09-23"
+    _change_note: ClassVar[Optional[str]] = "Remove nonexistent singular quote output; bind the values array."
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/data_korea_stock.py

@@ -85,6 +85,11 @@ class KoreaStockMarketDataNode(BaseNode):
         "Item-based execution: pair with SplitNode to query multiple domestic stocks in sequence",
         "is_tool_enabled=True — AI Agent can call this node to look up KRX stock prices autonomously",
         "Real-trading only — KoreaStock product does not support paper trading (paper_trading=False enforced)",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "In replay the one-shot quote records its `values` port as a flat row list at nodes.<id>.output.values; this is not the realtime symbol-keyed ohlcv_data shape",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -195,7 +200,6 @@ class KoreaStockMarketDataNode(BaseNode):
         InputPort(name="trigger", type="signal", description="i18n:ports.trigger", required=False),
     ]
     _outputs: List[OutputPort] = [
-        OutputPort(name="value", type="market_data", description="i18n:ports.market_data_value", fields=KOREA_STOCK_PRICE_DATA_FIELDS),
         OutputPort(
             name="values",
             type="array",
@@ -204,9 +208,9 @@ class KoreaStockMarketDataNode(BaseNode):
         ),
     ]
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.0.1"
+    _updated_at: ClassVar[str] = "2026-09-23"
+    _change_note: ClassVar[Optional[str]] = "Remove nonexistent singular quote output; bind the values array."
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/data_stock.py

@@ -87,6 +87,11 @@ class OverseasStockMarketDataNode(BaseNode):
         "is_tool_enabled=True — AI Agent can call this node to look up live prices autonomously",
         "Broker connection is auto-injected via DAG traversal — no explicit binding needed",
         "REST-based polling; for continuous streaming use OverseasStockRealMarketDataNode",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "On a schedule tick this node re-runs and needs a fresh recording in that tick frame; on a realtime event only nodes downstream of the streaming source re-run",
+        "In replay the one-shot quote records its `values` port as a flat row list at nodes.<id>.output.values; this is not the realtime symbol-keyed ohlcv_data shape",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -196,26 +201,6 @@ class OverseasStockMarketDataNode(BaseNode):
         InputPort(name="trigger", type="signal", description="i18n:ports.trigger", required=False),
     ]
     _outputs: List[OutputPort] = [
-        OutputPort(
-            name="value",
-            type="market_data",
-            description="i18n:ports.market_data_value",
-            fields=PRICE_DATA_FIELDS,
-            example={
-                "symbol": "AAPL",
-                "exchange": "NASDAQ",
-                "price": 187.45,
-                "change": -2.34,
-                "change_pct": -1.23,
-                "volume": 12_345_678,
-                "open": 189.10,
-                "high": 190.02,
-                "low": 186.90,
-                "close": 187.45,
-                "per": 28.5,
-                "eps": 6.57,
-            },
-        ),
         OutputPort(
             name="values",
             type="array",
@@ -224,9 +209,9 @@ class OverseasStockMarketDataNode(BaseNode):
         ),
     ]
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.0.1"
+    _updated_at: ClassVar[str] = "2026-09-23"
+    _change_note: ClassVar[Optional[str]] = "Remove nonexistent singular quote output; bind the values array."
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/display.py

@@ -190,7 +190,7 @@ class TableDisplayNode(BaseDisplayNode):
         {
             "pattern": "Binding a single dict (not a list) to TableDisplayNode data",
             "reason": "TableDisplayNode expects list[dict]. A plain dict renders as a single-column table with keys, which is rarely useful.",
-            "alternative": "Wrap single records in a list ([{{ nodes.market.value }}]) or use SummaryDisplayNode for single-object display.",
+            "alternative": "Wrap single records in a list ([{{ nodes.market.values[0] }}]) or use SummaryDisplayNode for single-object display.",
         },
         {
             "pattern": "Setting limit=100 for a live dashboard that updates every second",

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/infra.py

@@ -66,6 +66,9 @@ class StartNode(BaseNode):
         "Zero configuration — no fields, no credentials",
         "Produces a simple trigger signal that flows through main edges",
         "Always completes instantly and never fails",
+        "Exactly one StartNode per workflow; a graph rooted at a ScheduleNode is rejected (MISSING_START_NODE)",
+        "Emits no subsequent event: a StartNode-only workflow runs once and cannot carry a duplicate or events scenario",
+        "The start port is a bare trigger signal; an output contract cannot assert a data type on it",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -75,7 +78,7 @@ class StartNode(BaseNode):
         },
         {
             "pattern": "Omitting StartNode and wiring ScheduleNode as the root",
-            "reason": "Works for scheduled workflows but some example templates and validators assume a StartNode anchor.",
+            "reason": "The engine rejects a graph rooted at a ScheduleNode (MISSING_START_NODE); a ScheduleNode is never the root.",
             "alternative": "Always include a StartNode and connect it to the ScheduleNode as the first main edge.",
         },
     ]
@@ -233,6 +236,9 @@ class ThrottleNode(BaseNode):
         "Two modes: 'skip' (drop during cooldown) and 'latest' (buffer newest, emit at window close)",
         "pass_first=True emits the first event immediately, useful for warm-start flows",
         "Emits _throttle_stats output for observability (received / passed / skipped counts)",
+        "Cooldown state persists in context.node_state, so it survives re-triggers within one execution: with pass_first=true the first event passes and a further event within interval_sec is throttled",
+        "While throttled it emits only its `_`-prefixed ports (_throttled/_throttle_stats), which never leak downstream, so a node placed after it does not re-execute",
+        "interval_sec is bounded between 0.1 and 300 seconds",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -974,7 +980,8 @@ class IfNode(BaseNode):
         "12 comparison operators including ==, !=, >, >=, <, <=, in, not_in, contains, not_contains, is_empty, is_not_empty",
         "Three outputs: `true` / `false` payloads + `result` boolean — edges use from_port to route",
         "Expression binding on both `left` and `right` operands — supports full `{{ nodes.X.Y }}` syntax",
-        "Cascading skip — downstream of the inactive branch is auto-skipped by the executor",
+        "Skips only descendants of the untaken port that have no other active path; a node also fed by a non-If upstream still runs when that upstream completes",
+        "Evaluates exactly one left/operator/right comparison per node; the untaken branch is the false port, and a CodeNode returning false skips nothing",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.0.1 → programgarden_core-2.2.0}/programgarden_core/nodes/open_orders_futures.py

@@ -62,6 +62,13 @@ class OverseasFuturesOpenOrdersNode(BaseNode):
         "Returns `open_orders` (list of unfilled futures order dicts) and `count` (integer) ports",
         "is_tool_enabled=True — AI Agent can query pending futures orders as a tool call",
         "Works in both paper_trading and real trading modes via the upstream OverseasFuturesBrokerNode",
+        "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
+        "Only those five connection keys are allowed; each present key is a nonempty string except paper_trading, which is a boolean",
+        "A recording is {request, as_of, item, output}: a single call sets item to null and a per-symbol-iterated call records {items: {\"EXCHANGE:SYMBOL\": record}}; output keys must be declared ports and row fields must be among the port's documented fields",
+        "Retained across realtime events (queried once at startup); re-runs on every schedule tick",
+        "Each recorded row needs a non-empty unique order_id, and count must equal the number of rows; a snapshot lists only still-open orders, so a guard blocks on presence (count > 0), not on a derived remaining_quantity",
+        "order_events (modify/cancel completions: [{request_node, symbol_key, event_id, applied}]) is a top-level field of the recording beside request/as_of/output, never inside output",
+        "An order this workflow did not place (any non-SIM- id) is taken exactly as recorded: never retired by order_events, never reserving simulated cash, and listed in every OpenOrders recording of the same tick or in none",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {