feat: add PUSH_STACK instruction for manual stack push in composition chains.

Author: JohnRichard4096

demos/13_ret_far.py

@@ -1,28 +1,20 @@
-"""13_ret_far.py — Manual push + GOTO + RET_FAR pop-and-return
+"""13_ret_far.py — PUSH_STACK + GOTO + RET_FAR pop-and-return
 
 Usage:
     python demos/13_ret_far.py
 """
 
 import asyncio
 
-from amrita_sense import ALIAS, NOP, Node, PointerVector, WorkflowInterpreter
-from amrita_sense.instructions import GOTO, RET_FAR
+from amrita_sense import ALIAS, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, PUSH_STACK, RET_FAR
 
 
 @Node()
 async def start() -> None:
     print("Start")
 
 
-@Node()
-async def save_ret_addr(pc: WorkflowInterpreter) -> None:
-    """Manually push a return destination onto _ret_addr_stack."""
-    print("  Saving return address...")
-    return_dest = PointerVector(pc.find_addr_alias("after"))
-    pc._ret_addr_stack.push(return_dest)
-
-
 @Node()
 async def doing_work() -> None:
     """The section we GOTO into."""
@@ -36,14 +28,14 @@ async def after_return() -> None:
 
 
 async def main() -> None:
-    print("=== RET_FAR example ===")
-    # Pattern: manual push → GOTO → RET_FAR pop-and-return
-    #   1) save_ret_addr pushes "after" address onto _ret_addr_stack
+    print("=== PUSH_STACK + GOTO + RET_FAR example ===")
+    # Pattern: PUSH_STACK → GOTO → RET_FAR pop-and-return
+    #   1) PUSH_STACK("after") pushes "after" address onto _ret_addr_stack
     #   2) GOTO("work") jumps to the work section
     #   3) RET_FAR() pops the saved address and jumps back
     comp = (
         start
-        >> save_ret_addr
+        >> PUSH_STACK("after")
         >> GOTO("work")
         >> ALIAS(after_return, "after")
         >> GOTO("end")

docs/guide/advanced/built-in_instruction_set/jump_clause.md

@@ -117,4 +117,4 @@ main = (
 )
 ```
 
-> **Manual stack management**: For scenarios requiring explicit control over the return address stack — such as early exit from nested scopes or custom stack unwinding — see the `RET_FAR` instruction documented in [Advanced Topic: Manual Stack Space Management](/guide/practice/manual-stack-management).
+> **Manual stack management**: `PUSH_STACK` + `GOTO` + `RET_FAR` give you explicit control over the return address stack, and can be combined with `ARCHIVED_NODES` for subroutine-like patterns. See [Advanced Topic: Manual Stack Space Management](/guide/practice/manual-stack-management) for full details.

docs/guide/practice/manual-stack-management.md

@@ -2,56 +2,48 @@
 
 The `CALL` instruction and `call_sub` method automatically manage the return address stack (`_ret_addr_stack`) for you: they push the current pointer before entering a subroutine, and the `finally` block pops it upon return. For most workflows, this is all you need.
 
-However, AmritaSense also exposes the return address stack for **manual control** via `RET_FAR`. The pattern is:
+However, AmritaSense also exposes the return address stack for **manual control** via `PUSH_STACK` and `RET_FAR`. The pattern is:
 
-1. **Manual push** — A node explicitly pushes a `PointerVector` onto `_ret_addr_stack`
+1. **PUSH_STACK** — Push an alias or address onto `_ret_addr_stack`
 2. **GOTO** — Jump somewhere else in the workflow
 3. **RET_FAR** — Pop the saved address and jump back
 
 This lets you implement custom call/return schemes that don't follow the rigid `CALL`/`call_sub` discipline.
 
 ## The Return Address Stack
 
-`_ret_addr_stack` is a `Stack[PointerVector]` on the `WorkflowInterpreter`. `CALL` pushes the current pointer onto it; the `finally` block of `call_sub` pops and restores it. But you can also push onto it directly from any node that has access to the interpreter via `POINTER_DEPENDS`.
+`_ret_addr_stack` is a `Stack[PointerVector]` on the `WorkflowInterpreter`. `CALL` pushes the current pointer onto it; the `finally` block of `call_sub` pops and restores it. With `PUSH_STACK`, you can push any alias target onto the stack directly from the composition chain without writing a custom node.
 
 ```mermaid
 sequenceDiagram
-    participant N as Node (manual push)
+    participant N as PUSH_STACK
     participant S as _ret_addr_stack
     participant W as Work Section
 
-    N->>S: push(PointerVector(return_addr))
+    N->>S: push(target_addr)
     N->>W: GOTO("work")
     W-->>W: execute...
     W->>S: RET_FAR pops
     W->>N: jump_far_ptr(base_addr)
 ```
 
-## RET_FAR
+## PUSH_STACK and RET_FAR
 
-`RET_FAR` is a factory function that creates a `RetFarNode`. At runtime, it does exactly one thing:
+- **`PUSH_STACK(alias_or_idata)`** — pushes the resolved address of a target alias (or a raw address list) onto `_ret_addr_stack`. It is a `PushStackNode`, placed directly in the `>>` chain.
+- **`RET_FAR()`** — pops the top entry from `_ret_addr_stack` and calls `jump_far_ptr` to jump to the saved address. Also a regular `BaseNode` placed in the composition chain.
 
-1. Pops the top entry from `_ret_addr_stack`
-2. Calls `pc.jump_far_ptr(ptr.base_addr)` to jump to the saved address
+Neither instruction should be `return`-ed from inside a `@Node()` function — place them directly in the `>>` chain.
 
-`RetFarNode` is a regular `BaseNode`, placed directly in the workflow composition — **not returned from inside another node**.
-
-## Example: Manual Push + GOTO + RET_FAR
+## Example: PUSH_STACK + GOTO + RET_FAR
 
 ```python
-from amrita_sense import ALIAS, NOP, Node, PointerVector, WorkflowInterpreter
-from amrita_sense.instructions import RET_FAR, GOTO
+from amrita_sense import ALIAS, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, PUSH_STACK, RET_FAR
 
 @Node()
 async def start() -> None:
     print("Start")
 
-@Node()
-async def save_ret_addr(pc: WorkflowInterpreter) -> None:
-    """Manually push a return destination onto _ret_addr_stack."""
-    return_dest = PointerVector(pc.find_addr_alias("after"))
-    pc._ret_addr_stack.push(return_dest)
-
 @Node()
 async def doing_work() -> None:
     """The section we GOTO into."""
@@ -64,7 +56,7 @@ async def after_return() -> None:
 
 comp = (
     start
-    >> save_ret_addr
+    >> PUSH_STACK("after")
     >> GOTO("work")
     >> ALIAS(after_return, "after")
     >> GOTO("end")
@@ -77,21 +69,73 @@ await WorkflowInterpreter(comp.render()).run()
 
 **Flow**:
 
-1. `save_ret_addr` pushes the address of `"after"` (i.e. `after_return`) onto `_ret_addr_stack`
+1. `PUSH_STACK("after")` pushes the address of `after_return` onto `_ret_addr_stack`
 2. `GOTO("work")` jumps to the `doing_work` node
-3. After `doing_work`, `RET_FAR` pops the saved `PointerVector` and jumps back to `after_return`
+3. After `doing_work`, `RET_FAR` pops the saved address and jumps back to `after_return`
 
 ## When to Use Manual Stack Management
 
 | Scenario                      | Use                                               |
 | ----------------------------- | ------------------------------------------------- |
 | Simple subroutine call/return | `CALL` + natural `call_sub` return                |
-| Custom return destination     | Manual push + `GOTO` + `RET_FAR`                  |
+| Custom return destination     | `PUSH_STACK` + `GOTO` + `RET_FAR`                 |
 | Multi-level stack unwinding   | Push multiple addresses, `RET_FAR` once per level |
 | Non-linear control flow       | Combine with `GOTO` for arbitrary jump patterns   |
 
+## Subroutine-like Pattern with ARCHIVED_NODES
+
+`PUSH_STACK` + `GOTO` + `RET_FAR` can be combined with `ARCHIVED_NODES` to create self-contained "subroutines" that are skipped during normal execution but can be entered via `GOTO`:
+
+```python
+from amrita_sense import ALIAS, ARCHIVED_NODES, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, PUSH_STACK, RET_FAR
+
+@Node()
+async def start() -> None:
+    print("Start")
+
+@Node()
+async def step1() -> None:
+    print("  Step 1")
+
+@Node()
+async def step2() -> None:
+    print("  Step 2")
+
+@Node()
+async def after_return() -> None:
+    print("Back here (via RET_FAR)")
+
+# Self-contained subroutine: normal flow skips it, GOTO enters it.
+# Execution inside: step1 >> step2 >> RET_FAR() → pop stack → return.
+subroutine = ARCHIVED_NODES(
+    ALIAS(NOP, "sub_entry"),  # entry point marker
+    step1,
+    step2,
+    RET_FAR(),
+)
+
+comp = (
+    start
+    >> PUSH_STACK("after")
+    >> GOTO("sub_entry")
+    >> ALIAS(after_return, "after")
+    >> subroutine
+)
+await WorkflowInterpreter(comp.render()).run()
+```
+
+**Flow**:
+
+1. `PUSH_STACK("after")` saves the return destination
+2. `GOTO("sub_entry")` enters the subroutine at `NOP` (the entry marker)
+3. `step1 >> step2` execute sequentially
+4. `RET_FAR()` pops the saved address and jumps back to `after_return`
+
+The `NOP` aliased as `"sub_entry"` acts as the named entry point — `GOTO` targets the alias, and the node itself is a no-op.
+
 ## Caution
 
-- **Stack integrity**: `RET_FAR` pops from `_ret_addr_stack` unconditionally. If the stack is empty, this raises an `IndexError`. Always push a corresponding address before reaching `RET_FAR`.
+- **Stack integrity**: `RET_FAR` pops from `_ret_addr_stack` unconditionally. If the stack is empty, this raises an `IndexError`. Always push a corresponding address (via `CALL` or `PUSH_STACK`) before reaching `RET_FAR`.
 - **Jump flag**: `RET_FAR` calls `jump_far_ptr` which is decorated with `@markup`, setting `_jump_marked = True`. The interpreter will NOT advance the pointer after `RET_FAR` — execution resumes at the jumped-to address.
-- **Not a subprogram instruction**: `RET_FAR` is a standalone node in the composition chain. Do NOT `return RET_FAR()` from inside a `@Node()` function — that return value is ignored. Place `RET_FAR()` directly in the `>>` chain.
+- **Not a subprogram instruction**: `PUSH_STACK` and `RET_FAR` are standalone nodes in the composition chain. Do NOT call them from inside a `@Node()` function — place them directly in the `>>` chain.

docs/zh/guide/advanced/built-in_instruction_set/jump_clause.md

@@ -117,4 +117,4 @@ main = (
 )
 ```
 
-> **手动栈空间管理**：对于需要显式控制返回地址栈的场景——如从嵌套作用域提前退出或自定义栈展开——请参见 `RET_FAR` 指令文档：[高级主题：手动栈空间管理分配](/zh/guide/practice/manual-stack-management)。
+> **手动栈空间管理**：`PUSH_STACK` + `GOTO` + `RET_FAR` 可显式控制返回地址栈，配合 `ARCHIVED_NODES` 还能实现子图式调用。完整说明请参见：[高级主题：手动栈空间管理分配](/zh/guide/practice/manual-stack-management)。

docs/zh/guide/advanced/external_interrupt.md

@@ -45,14 +45,14 @@ await interpreter.call_sub(
 
 ### `ARCHIVED_NODES` 的结构
 
-`ARCHIVED_NODES` 是一个自编译指令，它接收一系列 `ALIAS` 节点，自动生成如下结构：
+`ARCHIVED_NODES` 是一个自编译指令，它接收一系列节点（通常通过 `ALIAS` 标记以支持 `CALL` 寻址），自动生成如下结构：
 
 ```text
 SubprogramJumpNode -> ALIAS(node1, "name1") -> ALIAS(node2, "name2") -> ... -> NOP
 ```
 
 - `SubprogramJumpNode` 无条件跳转到末尾的 `NOP`，因此正常执行时整个存储区被跳过。
-- 每个节点都有别名，外部可以通过别名寻址，按需调用其中任意一个节点。
+- 每个节点可通过别名寻址，按需调用其中任意一个。
 
 ### 示例
 

docs/zh/guide/practice/manual-stack-management.md

@@ -2,56 +2,48 @@
 
 `CALL` 指令和 `call_sub` 方法会为你自动管理返回地址栈（`_ret_addr_stack`）：进入子程序前压入当前指针，`finally` 块在返回时弹出。对于大多数工作流，这已经足够。
 
-然而，AmritaSense 也暴露了返回地址栈供**手动控制**，通过 `RET_FAR` 实现。其使用模式为：
+然而，AmritaSense 也暴露了返回地址栈供**手动控制**，通过 `PUSH_STACK` 和 `RET_FAR` 实现。其使用模式为：
 
-1. **手动压栈**——节点显式地将 `PointerVector` 压入 `_ret_addr_stack`
+1. **PUSH_STACK**——将别名或地址压入 `_ret_addr_stack`
 2. **GOTO 跳转**——跳转到工作流中的其他位置
 3. **RET_FAR 返回**——弹出保存的地址并跳回
 
 这让你可以实现不遵循 `CALL`/`call_sub` 固定规则的自定义调用/返回方案。
 
 ## 返回地址栈
 
-`_ret_addr_stack` 是 `WorkflowInterpreter` 上的一个 `Stack[PointerVector]`。`CALL` 将当前指针压入其中；`call_sub` 的 `finally` 块弹出并恢复。但你也可以通过 `POINTER_DEPENDS` 获取解释器引用，从任意节点直接压栈。
+`_ret_addr_stack` 是 `WorkflowInterpreter` 上的一个 `Stack[PointerVector]`。`CALL` 将当前指针压入其中；`call_sub` 的 `finally` 块弹出并恢复。通过 `PUSH_STACK`，你可以在编排链中直接将任意别名目标压栈，无需编写自定义节点。
 
 ```mermaid
 sequenceDiagram
-    participant N as 节点（手动压栈）
+    participant N as PUSH_STACK
     participant S as _ret_addr_stack
     participant W as 工作区
 
-    N->>S: push(PointerVector(返回地址))
+    N->>S: push(target_addr)
     N->>W: GOTO("work")
     W-->>W: 执行...
     W->>S: RET_FAR 弹栈
     W->>N: jump_far_ptr(base_addr)
 ```
 
-## RET_FAR
+## PUSH_STACK 与 RET_FAR
 
-`RET_FAR` 是一个工厂函数，用于创建 `RetFarNode`。运行时，它只做一件事：
+- **`PUSH_STACK(alias_or_idata)`**——将目标别名（或裸地址列表）解析后的地址压入 `_ret_addr_stack`。它是一个 `PushStackNode`，直接放在 `>>` 链中。
+- **`RET_FAR()`**——从 `_ret_addr_stack` 弹出栈顶条目，通过 `jump_far_ptr` 跳转到保存的地址。同样是一个放在编排链中的 `BaseNode`。
 
-1. 从 `_ret_addr_stack` 弹出栈顶条目
-2. 调用 `pc.jump_far_ptr(ptr.base_addr)` 跳转到保存的地址
+两个指令都**不能**从 `@Node()` 函数内部 `return`——直接放在 `>>` 链中。
 
-`RetFarNode` 是一个普通的 `BaseNode`，直接放在工作流编排链中——**不能从另一个节点内部 `return` 出来**。
-
-## 示例：手动压栈 + GOTO + RET_FAR
+## 示例：PUSH_STACK + GOTO + RET_FAR
 
 ```python
-from amrita_sense import ALIAS, NOP, Node, PointerVector, WorkflowInterpreter
-from amrita_sense.instructions import RET_FAR, GOTO
+from amrita_sense import ALIAS, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, PUSH_STACK, RET_FAR
 
 @Node()
 async def start() -> None:
     print("开始")
 
-@Node()
-async def save_ret_addr(pc: WorkflowInterpreter) -> None:
-    """手动将返回目标地址压入 _ret_addr_stack。"""
-    return_dest = PointerVector(pc.find_addr_alias("after"))
-    pc._ret_addr_stack.push(return_dest)
-
 @Node()
 async def doing_work() -> None:
     """GOTO 跳入的工作区。"""
@@ -64,7 +56,7 @@ async def after_return() -> None:
 
 comp = (
     start
-    >> save_ret_addr
+    >> PUSH_STACK("after")
     >> GOTO("work")
     >> ALIAS(after_return, "after")
     >> GOTO("end")
@@ -77,21 +69,73 @@ await WorkflowInterpreter(comp.render()).run()
 
 **执行流程**：
 
-1. `save_ret_addr` 将 `"after"`（即 `after_return`）的地址压入 `_ret_addr_stack`
+1. `PUSH_STACK("after")` 将 `after_return` 的地址压入 `_ret_addr_stack`
 2. `GOTO("work")` 跳转到 `doing_work` 节点
-3. `doing_work` 执行完毕后，`RET_FAR` 弹出保存的 `PointerVector` 并跳回 `after_return`
+3. `doing_work` 执行完毕后，`RET_FAR` 弹出保存的地址并跳回 `after_return`
 
 ## 何时使用手动栈管理
 
-| 场景                | 方案                             |
-| ------------------- | -------------------------------- |
-| 简单子程序调用/返回 | `CALL` + 自然的 `call_sub` 返回  |
-| 自定义返回目标      | 手动压栈 + `GOTO` + `RET_FAR`    |
-| 多级栈展开          | 压入多个地址，每级一个 `RET_FAR` |
-| 非线性控制流        | 结合 `GOTO` 实现任意跳转模式     |
+| 场景                | 方案                              |
+| ------------------- | --------------------------------- |
+| 简单子程序调用/返回 | `CALL` + 自然的 `call_sub` 返回   |
+| 自定义返回目标      | `PUSH_STACK` + `GOTO` + `RET_FAR` |
+| 多级栈展开          | 压入多个地址，每级一个 `RET_FAR`  |
+| 非线性控制流        | 结合 `GOTO` 实现任意跳转模式      |
+
+## 子图式调用：配合 ARCHIVED_NODES 使用
+
+`PUSH_STACK` + `GOTO` + `RET_FAR` 可以与 `ARCHIVED_NODES` 结合，创建自包含的"子程序"——正常流跳过，通过 `GOTO` 进入：
+
+```python
+from amrita_sense import ALIAS, ARCHIVED_NODES, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, PUSH_STACK, RET_FAR
+
+@Node()
+async def start() -> None:
+    print("开始")
+
+@Node()
+async def step1() -> None:
+    print("  步骤 1")
+
+@Node()
+async def step2() -> None:
+    print("  步骤 2")
+
+@Node()
+async def after_return() -> None:
+    print("回到这里（通过 RET_FAR）")
+
+# 自包含子程序：正常流跳过，GOTO 进入。
+# 内部执行: step1 >> step2 >> RET_FAR() → 弹栈 → 返回。
+subroutine = ARCHIVED_NODES(
+    ALIAS(NOP, "sub_entry"),  # 入口标记
+    step1,
+    step2,
+    RET_FAR(),
+)
+
+comp = (
+    start
+    >> PUSH_STACK("after")
+    >> GOTO("sub_entry")
+    >> ALIAS(after_return, "after")
+    >> subroutine
+)
+await WorkflowInterpreter(comp.render()).run()
+```
+
+**执行流程**：
+
+1. `PUSH_STACK("after")` 保存返回目标
+2. `GOTO("sub_entry")` 通过别名进入子程序入口（即 `NOP`）
+3. `step1 >> step2` 顺序执行
+4. `RET_FAR()` 弹出保存的地址，跳回 `after_return`
+
+别名标记为 `"sub_entry"` 的 `NOP` 作为命名入口——`GOTO` 以别名定位，节点本身不执行任何操作。
 
 ## 注意事项
 
-- **栈完整性**：`RET_FAR` 无条件从 `_ret_addr_stack` 弹出。如果栈为空，会引发 `IndexError`。始终确保在到达 `RET_FAR` 之前已压入对应地址。
+- **栈完整性**：`RET_FAR` 无条件从 `_ret_addr_stack` 弹出。如果栈为空，会引发 `IndexError`。始终确保在到达 `RET_FAR` 之前已压入对应地址（通过 `CALL` 或 `PUSH_STACK`）。
 - **跳转标记**：`RET_FAR` 调用 `jump_far_ptr`，该方法被 `@markup` 装饰，会设置 `_jump_marked = True`。解释器在 `RET_FAR` 之后不会推进指针——执行会从跳转目标地址继续。
-- **不是子程序指令**：`RET_FAR` 是编排链中的独立节点。不要从 `@Node()` 函数内部 `return RET_FAR()`——该返回值会被忽略。将 `RET_FAR()` 直接放在 `>>` 链中。
+- **不是子程序指令**：`PUSH_STACK` 和 `RET_FAR` 是编排链中的独立节点。不要从 `@Node()` 函数内部调用它们——直接放在 `>>` 链中。