Feats: Event system;Update docsing

Author: JohnRichard4096

.gitignore

@@ -363,4 +363,7 @@ test-results.xml
 
 # Pytest
 
-test-results.xml
+test-results.xml
+
+# Other
+temp/

docs/.vitepress/config.mts

@@ -119,6 +119,10 @@ export default withMermaid({
                 text: "Dependency Injection",
                 link: "/guide/advanced/dependency_injection",
               },
+              {
+                text: "Event System",
+                link: "/guide/advanced/event_system",
+              },
               {
                 text: "Locating & Scope",
                 link: "/guide/advanced/locating_and_space",
@@ -178,6 +182,10 @@ export default withMermaid({
                 text: "Self-Compile Instructions",
                 link: "/reference/api/self-compile",
               },
+              {
+                text: "SuspendObjectStream",
+                link: "/reference/api/suspend-object-stream",
+              },
             ],
           },
           { text: "Appendix", link: "/guide/appendix" },
@@ -257,6 +265,10 @@ export default withMermaid({
                 text: "依赖注入",
                 link: "/zh/guide/advanced/dependency_injection",
               },
+              {
+                text: "事件系统",
+                link: "/zh/guide/advanced/event_system",
+              },
               {
                 text: "定位与空间",
                 link: "/zh/guide/advanced/locating_and_space",
@@ -310,6 +322,10 @@ export default withMermaid({
               { text: "类型系统", link: "/zh/reference/api/types" },
               { text: "异常系统", link: "/zh/reference/api/exceptions" },
               { text: "自编译指令", link: "/zh/reference/api/self-compile" },
+              {
+                text: "SuspendObjectStream",
+                link: "/zh/reference/api/suspend-object-stream",
+              },
             ],
           },
           { text: "附录", link: "/zh/guide/appendix" },

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

@@ -5,8 +5,6 @@
 > **Common foundation**
 > Both rely on the same alias registry (`ALIAS`), perform address resolution during `_pre_check`, and use the `@markup` decorator to manage jump markers. Understanding these common mechanisms helps clarify the difference between them.
 
----
-
 ## Non-self-compiled direct nodes
 
 `GOTO` and `CALL` are **not** `SelfCompileInstruction`. They do not expand into `NodeCompose` at compile time; instead, they exist as single jump nodes in the workflow array.
@@ -17,8 +15,6 @@ That means:
 - runtime behavior is expressed entirely through address resolution and pointer rewriting
 - they do not create new Bubbles or nesting scopes
 
----
-
 ## GOTO
 
 `GOTO` is a factory wrapper for `JumpNode`. At runtime, it calls the interpreter’s `jump_to` method and performs a **one-way, non-returning** pointer rewrite.
@@ -42,8 +38,6 @@ That means:
 - **Branch merging**: multiple conditional branches converge on the same `NOP` point.
 - **State machine transitions**: jump to different next states based on runtime conditions.
 
----
-
 ## CALL
 
 `CALL` is a factory wrapper for `CallNode`. At runtime, it calls the interpreter’s `call_sub` method and performs a **push → jump → execute → pop** subroutine call.
@@ -69,8 +63,6 @@ That means:
 - **Modular decomposition**: split complex workflows into independent subprocedures and keep the main flow simple.
 - **Interrupt handling**: external systems can invoke predefined interrupt handlers via `call_sub(interrupt=True)`.
 
----
-
 ## GOTO vs CALL: comparison
 
 | Feature           | GOTO                                       | CALL                                       |
@@ -81,17 +73,13 @@ That means:
 | Use cases         | one-way jump, branch merge, error handling | subroutine reuse, modular flow, interrupts |
 | Underlying API    | `pc.jump_to(addr)`                         | `pc.call_sub(addr)`                        |
 
----
-
 ## Usage notes
 
 - **GOTO is not a substitute for loops**: `GOTO` does not provide return semantics. Jumping out of a loop with `GOTO` will not correctly manage the loop state. Use `BreakLoop` for loop exit and `CALL` for reusable subroutines.
 - **CALL targets must be addressable**: the target node or entry node must have `address_able=True`, which is required by `ALIAS`.
 - **GOTO and CALL share alias space**: both look up aliases in `alias2vector_map`. Avoid alias name conflicts.
 - **CALL return depends on stack integrity**: a `GOTO` inside a subroutine sets `_jump_marked`, which can cause `call_sub` to skip stack restoration. Understand that `GOTO` inside a subroutine can override normal return behavior.
 
----
-
 ## Example
 
 ```python

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

@@ -2,8 +2,6 @@
 
 `NOP` and `INTERRUPT` are two special atomic instructions in AmritaSense’s instruction set. They are not `SelfCompileInstruction` and have no compile-time expansion. Instead, they exist as individual nodes in the workflow, and their behavior is defined purely at runtime.
 
----
-
 ## NOP sentinel instruction
 
 `NOP` (No Operation) is an **empty sentinel node**. Its significance is not in doing work, but in **standing in place** to provide a valid jump target.
@@ -37,8 +35,6 @@ IF(cond, GOTO("then")) >> ... >> ALIAS(NOP, "end_if")
 
 **As an empty ELSE branch**: `IF(cond, do).ELSE(NOP)` expresses “do nothing when the condition is false” explicitly.
 
----
-
 ## INTERRUPT forced termination instruction
 
 `INTERRUPT` is the workflow’s **emergency stop button**. When executed, the workflow terminates immediately and unconditionally.
@@ -76,8 +72,6 @@ The only exception is when `InterruptNotice` is explicitly included in the `exce
 - **Emergency safety stop**: insert `INTERRUPT` in the workflow when an unrecoverable error or dangerous condition occurs.
 - **Timeout handling**: a node can check timeout conditions before execution and raise `INTERRUPT` to force termination.
 
----
-
 ## Comparison summary
 
 |                  | NOP                                       | INTERRUPT                      |

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

@@ -2,8 +2,6 @@
 
 AmritaSense provides a complete exception handling instruction system that aligns closely with Python’s `try-except-else-finally`. Before using it, ask yourself: **when should you use instruction-based exception handling, and when should you write `try-except` inside a node?**
 
----
-
 ## Choosing between two exception handling modes
 
 ### Inline try-catch inside a node
@@ -56,8 +54,6 @@ TRY(call_api).CATCH(TimeoutError, use_cache).CATCH(AuthError, refresh_token).FIN
 > **Core principle**
 > Use Python for exceptions that belong inside a node. Use instructions for workflow-level exception control. They can be mixed — a TRY block may contain nodes that use their own inline try-catch.
 
----
-
 ## Instruction syntax and semantics
 
 ### Full syntax
@@ -86,8 +82,6 @@ TRY(do).CATCH(exc1, handler1).CATCH(exc2, handler2).FINALLY(cleanup)
 2. A single `TRY` structure may define at most one `FINALLY` and one `THEN`.
 3. `CATCH` may appear multiple times and is matched top-to-bottom with short-circuit behavior.
 
----
-
 ## Runtime execution logic
 
 `TryClause` is a `SelfCompileInstruction` and expands at compile time into:
@@ -110,8 +104,6 @@ The runtime behavior of `TryNode` is:
    - if no catch matches, re-raise the exception
 4. **Regardless of exception**: the `finally` block executes via `call_near` if defined.
 
----
-
 ## Exception penetration rules
 
 When the `WorkflowInterpreter` is initialized with `exception_ignored`, those exception types are not caught by any `CATCH` block:
@@ -129,8 +121,6 @@ When `TryNode` encounters one of these exceptions, it re-raises it immediately,
 - **`BreakLoop`** can jump out of the innermost loop and is not intercepted by intermediate exception handlers.
 - **Critical errors** can bypass local fault tolerance and reach a global handler.
 
----
-
 ## Usage examples
 
 ### Instruction orchestration: API call fault tolerance
@@ -178,8 +168,6 @@ TRY(risky_op)\
 TRY(acquire_resource).FINALLY(release_resource)
 ```
 
----
-
 ## Dependency injection in exception handlers
 
 Nodes in `CATCH`, `THEN`, and `FINALLY` blocks can use `Depends` normally. The caught exception object itself can also be injected into a handler node — this is a unique advantage of instruction-based exception handling over inline try-catch.

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

@@ -2,8 +2,6 @@
 
 AmritaSense provides two standard loop paradigms: `WHILE` (check before executing) and `DO-WHILE` (execute before checking). Both are `SelfCompileInstruction` and expand at compile time into a fixed structure containing jump nodes. At runtime, the loop semantics are implemented entirely through pointer offsets and `jump_near`, without any external state flags.
 
----
-
 ## Compile-time expansion structure
 
 ### WHILE loop
@@ -41,8 +39,6 @@ AmritaSense provides two standard loop paradigms: `WHILE` (check before executin
 > **Key difference**
 > WHILE checks the condition before the loop body; DO-WHILE executes the loop body before the condition. Both use `NOP` as the unified loop exit.
 
----
-
 ## Runtime execution flow
 
 ### WHILE
@@ -75,8 +71,6 @@ Within `action` or `do_node`, you can `raise BreakLoop` to implement `break` sem
 
 Returning early from `action` or `do_node` ends the current node execution. The interpreter then naturally advances to `CheckUpNode` (for `WHILE`) or `DowhileNode` (for `DO-WHILE`), starting the next iteration. This behavior is equivalent to `continue`.
 
----
-
 ## `GOTO` restrictions inside loops
 
 The compile-time structure of `WHILE` and `DO-WHILE` is fixed. `WhileNode` and `DONode` rely on `call_offset` and `jump_near` relative offsets to perform condition checks and body execution.
@@ -89,8 +83,6 @@ If a `GOTO` inside the loop body jumps outside the loop structure:
 
 Therefore, **do not use `GOTO` to jump out of a loop**. Use `BreakLoop` to exit the loop, and use `CALL` for reusable subroutine execution.
 
----
-
 ## Usage example
 
 ```python
@@ -125,8 +117,6 @@ def fetch():
 retry = DO(fetch).WHILE(has_more)
 ```
 
----
-
 ## When to use WHILE vs DO-WHILE
 
 | Scenario                                            | Recommended |
@@ -136,7 +126,5 @@ retry = DO(fetch).WHILE(has_more)
 | The condition must be evaluated before the body     | `WHILE`     |
 | The condition only becomes available after the body | `DO-WHILE`  |
 
----
-
 > **Condition nodes are nodes**
 > Unlike graph model frameworks that hardcode conditions into routing functions, AmritaSense treats the loop condition itself as a `Node[bool]`. That means the condition can be asynchronous, can accept dependency injection, and can be suspended before evaluation. This is the direct embodiment of the “everything is a node” philosophy in loop structures.

docs/guide/advanced/child_node.md

@@ -4,8 +4,6 @@ AmritaSense provides a complete subroutine call mechanism. Unlike `GOTO`’s one
 
 This chapter starts from the interpreter’s low-level API and explains call stack management, argument passing, and how to invoke subroutines in node code.
 
----
-
 ## 4.3.1 `call_sub`: the interpreter’s low-level call primitive
 
 `call_sub` is a low-level call primitive provided by `WorkflowInterpreter`. Both the composition-level `CALL` instruction and node-internal subroutine calls ultimately use it. Its core workflow is:
@@ -30,8 +28,6 @@ This design lets the same call primitive serve both internal reuse and external
 
 After the subroutine completes, `call_sub` checks the `_jump_marked` flag. If the subroutine executed a jump operation such as `GOTO`, that flag is set to `True`. In that case, the `finally` block **does not restore the original execution pointer** — the new jump target is preserved, and the interpreter continues from there. This ensures subroutine-internal jumps can correctly affect the main workflow control flow.
 
----
-
 ## 4.3.2 Passing arguments to subroutines
 
 `call_sub` supports passing extra positional and keyword arguments directly. These arguments are merged into the available parameter pool for the subroutine’s entry node during dependency resolution.
@@ -61,8 +57,6 @@ Subroutine nodes can use both operands passed via `call_sub` and dependencies de
 If a subroutine entry node declares a dependency via `Depends` and that provider returns `None`, the workflow raises an exception and terminates. This is different from an event system where a `None` return might be treated as a “skip.” Node execution is atomic, and failed dependency resolution means the node cannot run.
 :::
 
----
-
 ## 4.3.3 Call stack and return address restoration
 
 The call stack is the core data structure of AmritaSense’s subroutine mechanism, ensuring correct return behavior for nested calls.
@@ -99,8 +93,6 @@ Every `call_sub` pushes the current address, and every return pops the top addre
 
 If the subroutine executes `GOTO` or another jump operation, `_jump_marked` is set to `True`. In that case, `call_sub` skips restoring the saved pointer and does not pop the return address. This means the subroutine’s internal jump can “override” normal return behavior. Developers should understand that `GOTO` inside a subroutine may prevent automatic return stack cleanup and may require explicit stack management.
 
----
-
 ### Summary
 
 `call_sub` and the call stack form the low-level foundation of AmritaSense’s subroutine system. The composition-level `CALL` instruction is a declarative wrapper around this primitive, while node-internal `call_sub` gives developers full freedom to construct dynamic call chains in code. In the next chapter, we’ll explore how to combine these features with external interruption to build subroutine libraries that can be safely injected from outside.

docs/guide/advanced/custom_instruction.md

@@ -2,8 +2,6 @@
 
 AmritaSense’s built-in instruction set already covers core control flow such as conditionals, loops, and exception handling. But when those basic instructions repeatedly appear in fixed patterns, you can encapsulate them as **new instructions** with `SelfCompileInstruction`. This extension does not modify the interpreter; it only expands into standard node compositions at compile time, and at runtime it behaves exactly like built-in instructions.
 
----
-
 ## 4.7.1 Selfcompiled instruction interface: `SelfCompileInstruction`
 
 `SelfCompileInstruction` is an abstract base class that defines the unified entry for all self-compiled instructions:
@@ -32,8 +30,6 @@ class SelfCompileInstruction(ABC):
 3. If the expanded structure includes jumps, address calculation must be handled inside `extract()`.
 4. The returned `NodeCompose` is automatically rendered; you do not need to call `render()` manually.
 
----
-
 ## 4.7.2 Implementation pattern: `extract()` and address calculation
 
 The core task in implementing a custom instruction is mapping an “intention” to a concrete sequence of nodes. This mapping involves three steps:
@@ -82,8 +78,6 @@ This is equivalent to writing:
 workflow = start >> log_start >> process_data >> log_end >> end
 ```
 
----
-
 ## 4.7.3 Example 1: retry wrapper
 
 Wrapping a potentially failing node with retry logic is a typical use case for self-compiled instructions.
@@ -153,8 +147,6 @@ WHILE(lambda: retries < self._max).ACTION(TRY(call_api).CATCH(Exception, on_erro
 - Jump addresses are handled by the built-in instructions, so `RetryClause` does not need to manage offsets manually.
 - Users see only `RetryClause(...)`, while the expansion remains transparent.
 
----
-
 ## 4.7.4 Example 2: conditional execution wrapper
 
 Encapsulate the common pattern “execute a node when a condition is true, otherwise skip it” as a single instruction.
@@ -195,8 +187,6 @@ class ExecuteWhenElse(SelfCompileInstruction):
         )
 ```
 
----
-
 ## Design principles for custom instructions
 
 1. **Encapsulate patterns, not logic**: custom instructions should encapsulate recurring composition patterns (retry, conditional execution, timeout protection), not concrete business logic. Business logic belongs inside nodes.

docs/guide/advanced/custom_node.md

@@ -2,8 +2,6 @@
 
 In AmritaSense, nodes are the basic units of execution flow. Built-in instructions are ultimately expanded into node compositions, while custom nodes are the direct way developers encapsulate their business logic. This chapter explains node essence, lifecycle, and how to use `POINTER_DEPENDS` to gain full interpreter control when necessary.
 
----
-
 ## 4.6.1 The `@Node` decorator and node essence
 
 The `@Node()` decorator converts an ordinary Python function or coroutine into a workflow node. It does not do anything complex — it simply packages the function object, signature metadata, and a few data fields into a `Node` instance.
@@ -34,8 +32,6 @@ Each node is essentially a thin wrapper around the original function. It preserv
 
 **Everything is a node** — this is AmritaSense’s core philosophy. Conditionals, loop bodies, exception handlers, and GOTO targets are all `Node` or `BaseNode` instances. Custom nodes are no exception.
 
----
-
 ## 4.6.2 Handling sync and async nodes
 
 AmritaSense unifies synchronous and asynchronous nodes. In `_call()`, it decides how to execute based on `iscoroutinefunction` and `wrap_to_async`.
@@ -84,8 +80,6 @@ This is appropriate for extremely lightweight sync operations, such as simple co
 
 The `Node` class is also memory-optimized using `__slots__`, avoiding a default `__dict__` and keeping each node as lightweight as possible.
 
----
-
 ## 4.6.3 Node lifecycle and atomicity
 
 ### Lifecycle
@@ -108,8 +102,6 @@ Node atomicity is guaranteed by the **interpreter lock** and **cooperative inter
 
 If a custom node class inherits from `BaseNode`, it can override `_pre_check`. This method is called before each node execution and can access the current interpreter instance to perform address validation, alias lookup, or other checks. `CallNode` and `JumpNode` both use this mechanism to resolve aliases to addresses before their first execution.
 
----
-
 ## 4.6.4 `POINTER_DEPENDS`: access to the interpreter
 
 `POINTER_DEPENDS` is a special dependency injection factory that allows a node to obtain the current `WorkflowInterpreter` instance.
@@ -140,7 +132,22 @@ With interpreter access, nodes can directly manipulate pointers and the call sta
 
 Therefore, **inject `POINTER_DEPENDS` only when necessary**. Most nodes should use normal Python logic and composition-level instructions (`IF`, `WHILE`, `CALL`) to express control flow, and only directly access the interpreter when instructions cannot express the desired behavior.
 
----
+## 4.6.5 Safe runtime integration
+
+Custom nodes that need runtime context should use `POINTER_DEPENDS` to access `WorkflowInterpreter` rather than manipulating internal interpreter state directly. The interpreter exposes safe APIs such as:
+
+- `jump_to(addr)`
+- `jump_near(addr)`
+- `jump_offset(offset)`
+- `call_sub(addr, *args, interrupt=False)`
+- `find_addr_alias(alias)`
+- `object_io`
+
+Because `object_io` is a generic `SuspendObjectStream` subclass, custom nodes can also participate in external suspend/resume or streaming I/O patterns without changing the core interpreter loop.
+
+::: tip
+If you only need data dependencies, prefer `Depends(...)` with provider functions. Use `POINTER_DEPENDS` only for workflow control or low-level runtime inspection.
+:::
 
 ### Summary