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

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

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

{programgarden_core-2.1.0 → 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.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → 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.1.0 → 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.1.0 → 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.1.0 → 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.1.0 → 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.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/code.py

@@ -168,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]]] = [
         {

{programgarden_core-2.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → 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.1.0 → 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]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/open_orders_korea_stock.py

@@ -61,6 +61,13 @@ class KoreaStockOpenOrdersNode(BaseNode):
         "Returns `open_orders` (list of unfilled domestic order dicts) and `count` (integer) ports",
         "is_tool_enabled=True — AI Agent can query pending Korea stock orders as a tool call",
         "Real trading only — KoreaStockBrokerNode does not support paper_trading mode",
+        "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]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/open_orders_stock.py

@@ -62,6 +62,13 @@ class OverseasStockOpenOrdersNode(BaseNode):
         "Returns `open_orders` (list of unfilled order dicts) and `count` (integer) ports",
         "is_tool_enabled=True — AI Agent can query pending orders as a tool call",
         "One-shot REST call: suitable for scheduled checks or pre-trade validation steps",
+        "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]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/order.py

@@ -391,6 +391,16 @@ class OverseasStockNewOrderNode(BaseOrderNode):
         "retry is disabled by default (resilience.retry.enabled=False); only pure network-connection failures may be retried, never a submitted order",
         "US daytime (Blue Ocean) session accepts LIMIT orders only — a market order is refused at intake with rsp_cd=00891 and no order number (00891 is a generic order-price rejection: it was also observed on 2026-09-24 for a price of 1 USD or more sent with more than two decimals — '주문단가 오류. $1이상은 소수점 2째 자리까지 입력가능합니다'). A workflow scheduled across both the daytime and the regular overnight session must therefore use order_type='limit' for it to work in both.",
         "A limit order needs a price. Buy orders fall back to a current-price lookup, and so do sell orders since engine 1.37.3, but that lookup (g3101) only accepts exchange codes 81/82 — it fails for a holding listed on any other market. Prefer feeding the price the account balance already carries: price='{{ item.current_price }}'.",
+        "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",
+        "Every executed new-order node places an order, booked in replay as SIM-<node_id> (SIM-<node_id>#2 on a repeat, SIM-REPLACE-<modify_node> for a replacement); a node behind a false IfNode books nothing, and one intended order maps to one new-order node",
+        "The result port is an array of one order object {order_id, exchange, symbol, side, quantity, price, status}",
+        "A rejected order is still booked with status rejected; a timeout books unknown and reserves the cost; cash is debited on fills only; live_order_count is always 0 in replay",
+        "It may depend only on its gating IfNode; any other upstream completion triggers it even when the gate is false",
+        "The engine does not refuse a buy for a held symbol; only a workflow guard can block buying while holding",
+        "An overseas-stock market buy is submitted live as a limit order at the current price (LS accepts limit buys only; sells may be market or limit); replay mirrors it, so the booked intent is order_type limit at the quote",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -659,6 +669,12 @@ class OverseasStockModifyOrderNode(BaseModifyOrderNode):
         "Modifies price and/or quantity of a single open order identified by original_order_id + symbol + exchange",
         "Retry disabled by default (same safety rationale as new-order nodes — a duplicate modify can cause unintended fills)",
         "Rate-limited to 1 concurrent execution with 5-second minimum interval to prevent rapid repeated modifications",
+        "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",
+        "A modify is only acknowledged in the tick; the original order is replaced only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
+        "Replay supports limit-to-limit modification only; the replacement order is booked as SIM-REPLACE-<node_id>",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -946,6 +962,11 @@ class OverseasStockCancelOrderNode(BaseModifyOrderNode):
         "Cancels a single open order identified by original_order_id + symbol + exchange; auto-iterate to cancel multiple",
         "Retry disabled by default — a duplicate cancel on an already-cancelled order returns an error from the broker",
         "Rate-limited to 1 concurrent execution with 5-second minimum interval",
+        "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",
+        "A cancel is only acknowledged in the tick; the order is cancelled only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -1184,6 +1205,15 @@ class OverseasFuturesNewOrderNode(BaseOrderNode):
         "is_tool_enabled=True — AI Agent can call this node as a tool to place futures orders",
         "Retry disabled by default to prevent duplicate futures contract positions",
         "Rate-limited to 1 concurrent execution with 5-second minimum interval",
+        "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",
+        "Every executed new-order node places an order, booked in replay as SIM-<node_id> (SIM-<node_id>#2 on a repeat, SIM-REPLACE-<modify_node> for a replacement); a node behind a false IfNode books nothing, and one intended order maps to one new-order node",
+        "The result port is an array of one order object {order_id, exchange, symbol, side, quantity, price, status}",
+        "A rejected order is still booked with status rejected; a timeout books unknown and reserves the cost; cash is debited on fills only; live_order_count is always 0 in replay",
+        "It may depend only on its gating IfNode; any other upstream completion triggers it even when the gate is false",
+        "The simulator refuses a futures order that adds to a same-direction position; position reversal is not supported",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -1433,6 +1463,12 @@ class OverseasFuturesModifyOrderNode(BaseModifyOrderNode):
         "Modifies price and/or quantity of a single open futures order by original_order_id + symbol + exchange",
         "Supports the same exchanges as OverseasFuturesNewOrderNode (CME, EUREX, SGX, HKEX)",
         "Retry disabled by default — duplicate modify on a futures order can create unexpected position delta",
+        "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",
+        "A modify is only acknowledged in the tick; the original order is replaced only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
+        "Replay supports limit-to-limit modification only; the replacement order is booked as SIM-REPLACE-<node_id>",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -1697,6 +1733,11 @@ class OverseasFuturesCancelOrderNode(BaseModifyOrderNode):
         "Cancels a single open futures order by original_order_id + symbol + exchange; auto-iterate for batch cancellation",
         "Retry disabled by default — a duplicate cancel returns a broker error if the order was already cancelled",
         "Rate-limited to 1 concurrent execution with 5-second minimum interval",
+        "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",
+        "A cancel is only acknowledged in the tick; the order is cancelled only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -1935,6 +1976,15 @@ class KoreaStockNewOrderNode(BaseOrderNode):
         "is_tool_enabled=True — AI Agent can call this node as a tool to place Korean stock orders",
         "Real-market only — paper_trading mode is not supported for Korean domestic stocks; KoreaStockBrokerNode enforces this",
         "Retry disabled by default to prevent duplicate KRW-denominated orders",
+        "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",
+        "Every executed new-order node places an order, booked in replay as SIM-<node_id> (SIM-<node_id>#2 on a repeat, SIM-REPLACE-<modify_node> for a replacement); a node behind a false IfNode books nothing, and one intended order maps to one new-order node",
+        "The result port is an array of one order object {order_id, exchange, symbol, side, quantity, price, status}",
+        "A rejected order is still booked with status rejected; a timeout books unknown and reserves the cost; cash is debited on fills only; live_order_count is always 0 in replay",
+        "It may depend only on its gating IfNode; any other upstream completion triggers it even when the gate is false",
+        "The engine does not refuse a buy for a held symbol; only a workflow guard can block buying while holding",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -2194,6 +2244,12 @@ class KoreaStockModifyOrderNode(BaseModifyOrderNode):
         "Modifies price and/or quantity of a single open Korean stock order by original_order_id + symbol",
         "No exchange field required — Korean stock symbol (6-digit code) uniquely identifies the instrument",
         "Retry disabled by default to prevent double-modification risk in KRW-denominated orders",
+        "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",
+        "A modify is only acknowledged in the tick; the original order is replaced only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
+        "Replay supports limit-to-limit modification only; the replacement order is booked as SIM-REPLACE-<node_id>",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -2447,6 +2503,11 @@ class KoreaStockCancelOrderNode(BaseModifyOrderNode):
         "Cancels a single open Korean stock order by original_order_id + symbol; auto-iterate for batch cancellation",
         "No exchange field required — Korean stock symbols uniquely identify KOSPI/KOSDAQ instruments",
         "Retry disabled by default — a duplicate cancel returns an error if the order was already cancelled",
+        "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",
+        "A cancel is only acknowledged in the tick; the order is cancelled only when a matching completion is observed via a downstream *OpenOrdersNode recording's top-level order_events array",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/realtime_futures.py

@@ -69,6 +69,11 @@ class OverseasFuturesRealMarketDataNode(BaseNode):
         "Supports CME, EUREX, SGX, HKEX contracts — symbol must include contract month code (e.g., ESH26)",
         "Item-based execution: one subscription per node; use multiple nodes to watch multiple contracts",
         "Automatically re-subscribes after WebSocket reconnection events",
+        "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",
+        "In replay it records ohlcv_data (and its data alias) as a symbol-keyed object of bar lists keyed by the bare symbol, each bar carrying only date, open, high, low, close, volume",
+        "It does not record a top-level symbol port; the live node emits symbol only inside its event payload, so a recording that includes it is rejected",
+        "As a streaming source it emits market_data and realtime_update events; on each event only nodes downstream of it re-run, while upstream startup snapshots stay retained",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/realtime_korea_stock.py

@@ -68,6 +68,11 @@ class KoreaStockRealMarketDataNode(BaseNode):
         "Symbol format: 6-digit KRX code (e.g., '005930') without exchange field — domestic market implied",
         "Item-based execution: one subscription per node; use multiple nodes to watch multiple domestic stocks",
         "Real-trading only — KoreaStock product does not support paper trading",
+        "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",
+        "In replay it records ohlcv_data (and its data alias) as a symbol-keyed object of bar lists keyed by the bare symbol, each bar carrying only date, open, high, low, close, volume",
+        "It does not record a top-level symbol port; the live node emits symbol only inside its event payload, so a recording that includes it is rejected",
+        "As a streaming source it emits market_data and realtime_update events; on each event only nodes downstream of it re-run, while upstream startup snapshots stay retained",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/realtime_stock.py

@@ -71,6 +71,11 @@ class OverseasStockRealMarketDataNode(BaseNode):
         "Item-based execution: one subscription per node; use multiple nodes or SplitNode to watch several symbols",
         "Automatically re-subscribes after WebSocket reconnection events",
         "Does NOT include order book (bid/ask levels) — only trade (GSC) events; ask/bid from GSH are in the data port",
+        "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",
+        "In replay it records ohlcv_data (and its data alias) as a symbol-keyed object of bar lists keyed by the bare symbol, each bar carrying only date, open, high, low, close, volume",
+        "It does not record a top-level symbol port; the live node emits symbol only inside its event payload, so a recording that includes it is rejected",
+        "As a streaming source it emits market_data and realtime_update events; on each event only nodes downstream of it re-run, while upstream startup snapshots stay retained",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/session_gate.py

@@ -59,7 +59,7 @@ class SessionGateNode(BaseNode):
         'when_not_to_use':['An authoritative exchange-open or holiday feed is required.','Wait until opening: use TradingHoursFilterNode.'],
         'typical_scenarios':['ScheduleNode -> SessionGateNode -> IfNode(allowed) -> strategy','Reservation -> SessionGateNode -> IfNode(allowed) -> OrderNode'],
     }
-    _features: ClassVar[list[str]] = ['No credentials or network.','No sleeping and no dry-run bypass.','IANA timezone/DST and opening-weekday semantics.','Explicit IfNode controls downstream work.']
+    _features: ClassVar[list[str]] = ['No credentials or network.','No sleeping and no dry-run bypass.','IANA timezone/DST and opening-weekday semantics.','Explicit IfNode controls downstream work.','Output is a pure function of the evaluation instant and the configuration (windows are start-inclusive and end-exclusive, plus days, closed_dates and the IANA timezone); replay evaluates it at the scenario as_of.','Two frames at the same instant produce the same allowed value; an outside-window scenario must sit at an instant outside the window.','allowed skips nothing by itself; bind it to an IfNode and hang the order chain on the IfNode true edge.']
     _anti_patterns: ClassVar[list[dict[str,str]]] = [{'pattern':'Connect directly to an order and assume an ordinary edge checks allowed.','reason':'Edges sequence execution; false output does not automatically skip successors.','alternative':'Bind allowed to IfNode and use its true edge.'}]
     _node_guide: ClassVar[dict[str,Any]] = {
         'input_handling':'Configure timezone, windows, days and optional closed_dates. No current-time override is accepted from workflow data.',

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/nodes/trigger.py

@@ -95,6 +95,12 @@ class ScheduleNode(BaseNode):
         "Timezone-aware (IANA names) — 'America/New_York', 'Asia/Seoul', 'UTC'",
         "max_duration_hours caps total runtime; the scheduler exits cleanly at the limit",
         "enabled=False freezes the trigger without removing the node from the DAG",
+        "A tick re-executes the whole main flow: the ScheduleNode returns {trigger: true} without re-registering, so every node downstream of it runs again on each tick",
+        "Startup account and open-order snapshots are not retained across schedule ticks; they are retained only across realtime events",
+        "In replay a schedule_tick must fall on the cron's next firing instant after the previous frame, evaluated in this node's timezone (default America/New_York)",
+        "enabled=false emits no tick; ticks past count or max_duration_hours are refused; an invalid timezone is rejected at startup",
+        "Emits exactly one subsequent event type: schedule_tick",
+        "Requires exactly one StartNode upstream; the ScheduleNode is never the workflow root",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -319,6 +325,7 @@ class TradingHoursFilterNode(BaseNode):
         "`days` whitelist supports weekend-only or weekday-only flows",
         "Outside the window this node waits; `passed` activates on entry and `blocked` activates only on timeout/shutdown",
         "max_wait_hours safeguards long waits — the node timeouts instead of stalling forever",
+        "In replay an instant outside the window is refused (REPLAY_TIME_WAIT_BLOCKED); only in-window instants are replayable and the node then emits passed=true, so it cannot express an after-hours branch in a suite",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/programgarden_core/registry/node_registry.py

@@ -98,6 +98,20 @@ class NodeTypeSchema(BaseModel):
             "- pitfalls: List[str] — connection caveats and shape requirements"
         ),
     )
+    execution: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Machine-readable execution/replay semantics block (closed value "
+            "sets), derived from the engine's own replay contract code — never "
+            "authored per class. Populated by "
+            "`programgarden.replay_semantics.attach_execution` when the schema is "
+            "served through the tool registry; the core registry itself leaves it "
+            "None (core must not import programgarden). Keys: role, replay, "
+            "request, iteration, reruns_on, emits_events, on_event, output_ports, "
+            "dead_ports, internal_ports, reserved_output_ports, gating, order, "
+            "time_rules, venue."
+        ),
+    )
 
     # === Version metadata (UI change detection) ===
     version: str = Field(

{programgarden_core-2.1.0 → programgarden_core-2.2.0}/pyproject.toml

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