Update: README and tests.

JohnRichard4096 · Copilot · JohnRichard4096 · commit 7dedc6a5a024 · 2026-05-17T15:36:47.000+08:00
Co-authored-by: Copilot &lt;copilot@github.com&gt;
diff --git a/README.md b/README.md
@@ -27,10 +27,51 @@
 
 </center>
 
-## TODO
+AmritaSense is a **general-purpose workflow orchestration engine** that replaces traditional graph-based models with an **instruction set architecture**—treating workflows not as nodes-and-edges diagrams, but as programmable execution streams driven by a lightweight virtual machine.
 
-- [x] Main project
-- [x] [Documentation](https://sense.amritabot.com)
-- [ ] Workflow Debugger (Planned, in progress)
-- [x] Tests (In progress)
-- [ ] DEMOS (In progress)
+## Why AmritaSense?
+
+Most workflow engines force you into a graph mindset: define nodes, connect edges, manage state objects. AmritaSense takes a different path. You compose nodes and control flow just like writing ordinary code—the engine compiles them into a linear instruction sequence, then executes them step by step. The result: **zero scheduling overhead, native interrupt support, and the expressive power of assembly-level control flow.**
+
+## Core Features
+
+- **Complete Instruction Set**—`IF/ELIF/ELSE`, `WHILE/DO-WHILE`, `GOTO`/`CALL`, `TRY/CATCH/THEN/FIN`, `NOP`, `INTERRUPT`. All control flow is first-class, not simulated through graph routing.
+- **VM-Style Execution**—A program counter (`PointerVector`) and call stack drive execution. Jumps are integer operations, not graph traversals.
+- **Async-Native Suspend/Resume**—Two `Future` callbacks enable full workflow interruption at any node boundary. Built for debuggers and human-in-the-loop systems.
+- **Declarative Dependency Injection**—Nodes declare dependencies via function signatures. The engine resolves them at runtime with type matching and concurrent resolution.
+- **Ultra Lightweight**—Core interpreter is ~300 lines. Compiles 100,000 nodes in ~200ms. Runs anywhere from Raspberry Pi to cloud.
+- **Self-Compile Instructions**—Extend the instruction set with `SelfCompileInstruction`. Compile-time expansion, zero runtime overhead.
+
+## Installation
+
+```bash
+pip install amrita-sense
+```
+
+## Quick Look
+
+```python
+from amrita_sense import Node, WorkflowInterpreter as WorkflowPC, IF, NOP
+
+@Node()
+def condition() -> bool: return True
+
+@Node()
+def action(): print("Done")
+
+flow = IF(condition, action) >> NOP
+pc = WorkflowPC(flow.render())
+pc.run_sync()
+```
+
+## Documentation
+
+Full guides, concept explanations, and API reference at **[sense.amritabot.com](https://sense.amritabot.com)**.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+LGPL V2. See [LICENSE](LICENSE).
diff --git a/tests/test_runtime.py b/tests/test_runtime.py
@@ -1,8 +1,18 @@
+from typing import Any
+
 import pytest
+from amrita_core.hook.matcher import DependsFactory, MatcherFactory
 
+from amrita_sense.exceptions import (
+    DependsInjectFailed,
+    DependsResolveFailed,
+    InterruptNotice,
+    NullPointerException,
+)
 from amrita_sense.node.core import NodeCompose
 from amrita_sense.node.wrapper import Node as NodeDecorator
 from amrita_sense.runtime.workflow import WorkflowInterpreter
+from amrita_sense.types import PointerVector
 
 
 class TestWorkflowInterpreter:
@@ -62,3 +72,241 @@ def test_node():
 
         graph = interpreter.get_graph()
         assert graph is rendered
+
+    @pytest.mark.asyncio
+    async def test_run_step_by_runtime_args_unresolved_raises(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(simple_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+        interpreter._ava_args = (interpreter, DependsFactory(lambda: None))
+
+        original = MatcherFactory._do_runtime_resolve
+
+        async def _fake_runtime_resolve(*args: Any, **kwargs: Any) -> bool:
+            return False
+
+        MatcherFactory._do_runtime_resolve = classmethod(_fake_runtime_resolve)  # pyright: ignore[reportAttributeAccessIssue]
+        try:
+            with pytest.raises(
+                RuntimeError, match="Runtime arguments cannot be resolved"
+            ):
+                await interpreter.run_step_by().__anext__()
+        finally:
+            MatcherFactory._do_runtime_resolve = original
+
+    @pytest.mark.asyncio
+    async def test_run_step_by_interrupt_notice_clears_state(self):
+        @NodeDecorator()
+        def interrupt_node():
+            raise InterruptNotice("stop")
+
+        rendered = NodeCompose(interrupt_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        with pytest.raises(StopAsyncIteration):
+            await interpreter.run_step_by().__anext__()
+
+        assert not interpreter._pointer
+        assert not interpreter._ret_addr_stack
+        assert not interpreter._jump_marked
+
+    @pytest.mark.asyncio
+    async def test_call_raises_depends_resolve_failed(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(simple_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        original = MatcherFactory._resolve_dependencies
+        MatcherFactory._resolve_dependencies = classmethod(
+            lambda *args, **kwargs: (False, [], {}, {})  # pyright: ignore[reportAttributeAccessIssue]
+        )
+        try:
+            with pytest.raises(DependsResolveFailed):
+                await interpreter._call()
+        finally:
+            MatcherFactory._resolve_dependencies = original
+
+    @pytest.mark.asyncio
+    async def test_call_raises_depends_inject_failed(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(simple_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        original_resolve = MatcherFactory._resolve_dependencies
+        original_runtime = MatcherFactory._do_runtime_resolve
+        MatcherFactory._resolve_dependencies = classmethod(
+            lambda *args, **kwargs: (True, [], {}, {"x": DependsFactory(lambda: None)})  # pyright: ignore[reportAttributeAccessIssue]
+        )
+
+        async def _fake_runtime_resolve(*args: Any, **kwargs: Any) -> bool:
+            return False
+
+        MatcherFactory._do_runtime_resolve = classmethod(_fake_runtime_resolve)  # pyright: ignore[reportAttributeAccessIssue]
+        try:
+            with pytest.raises(DependsInjectFailed):
+                await interpreter._call()
+        finally:
+            MatcherFactory._resolve_dependencies = original_resolve
+            MatcherFactory._do_runtime_resolve = original_runtime
+
+    @pytest.mark.asyncio
+    async def test_call_uses_async_and_sync_no_wrap(self):
+        @NodeDecorator(wrap_to_async=False)
+        async def async_node():
+            return "async"
+
+        @NodeDecorator(wrap_to_async=False)
+        def sync_node():
+            return "sync"
+
+        rendered_async = NodeCompose(async_node).render()
+        interpreter_async = WorkflowInterpreter(rendered_async)
+        interpreter_async._pointer = PointerVector([0])
+        assert await interpreter_async._call() == "async"
+
+        rendered_sync = NodeCompose(sync_node).render()
+        interpreter_sync = WorkflowInterpreter(rendered_sync)
+        interpreter_sync._pointer = PointerVector([0])
+        assert await interpreter_sync._call() == "sync"
+
+    def test_find_addr_or_none_returns_none_for_invalid_path(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(simple_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        assert interpreter._find_addr_or_none([0, 0, 0]) is None
+
+    def test_advance_pointer_container_sibling_and_nested(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(simple_node, NodeCompose(simple_node)).render()
+        interpreter = WorkflowInterpreter(rendered)
+        interpreter._pointer = PointerVector([0])
+
+        assert interpreter._advance_pointer()
+        assert interpreter._pointer == PointerVector([1, 0])
+
+    def test_advance_pointer_backtrack_to_nested_sibling(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(
+            NodeCompose(simple_node), NodeCompose(simple_node)
+        ).render()
+        interpreter = WorkflowInterpreter(rendered)
+        interpreter._pointer = PointerVector([0, 0])
+
+        assert interpreter._advance_pointer()
+        assert interpreter._pointer == PointerVector([1, 0])
+
+    @pytest.mark.asyncio
+    async def test_call_offset_and_call_near_preserve_pointer(self):
+        @NodeDecorator()
+        def target_node():
+            return "target"
+
+        workflow = NodeCompose(target_node, target_node)
+        rendered = workflow.render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        interpreter._pointer = PointerVector([0])
+        result = await interpreter.call_offset(1)
+        assert result == "target"
+        assert interpreter._pointer == PointerVector([0])
+
+        interpreter._pointer = PointerVector([0])
+        result = await interpreter.call_near(1)
+        assert result == "target"
+        assert interpreter._pointer == PointerVector([0])
+
+    def test_jump_methods_modify_pointer_and_raise(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        interpreter = WorkflowInterpreter(NodeCompose(simple_node).render())
+        interpreter._pointer = PointerVector([1, 2])
+
+        interpreter.jump_to_top(0)
+        assert interpreter._pointer == PointerVector([0])
+
+        interpreter = WorkflowInterpreter(NodeCompose(simple_node).render())
+        interpreter._pointer = PointerVector([1, 2])
+        interpreter.jump_offset_top(1)
+        assert interpreter._pointer == PointerVector([2])
+
+        interpreter = WorkflowInterpreter(NodeCompose(simple_node).render())
+        interpreter._pointer = PointerVector([1, 2])
+        interpreter.jump_far_ptr([0, 1])
+        assert interpreter._pointer == PointerVector([0, 1])
+
+        interpreter = WorkflowInterpreter(NodeCompose(simple_node).render())
+        with pytest.raises(NullPointerException):
+            interpreter.jump_to([99])
+
+    @pytest.mark.asyncio
+    async def test_call_raises_on_nodecompose(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(NodeCompose(simple_node)).render()
+        interpreter = WorkflowInterpreter(rendered)
+        interpreter._pointer = PointerVector([0])
+
+        with pytest.raises(RuntimeError):
+            await interpreter._call()
+
+    def test_advance_pointer_empty_and_invalid(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        interpreter = WorkflowInterpreter(NodeCompose(simple_node).render())
+        interpreter._pointer = PointerVector()
+        assert not interpreter._advance_pointer()
+
+        interpreter._pointer = PointerVector([0, 0])
+        assert not interpreter._advance_pointer()
+
+    def test_advance_pointer_nested_and_backtrack(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(NodeCompose(simple_node), simple_node).render()
+        interpreter = WorkflowInterpreter(rendered)
+
+        interpreter._pointer = PointerVector([0])
+        assert interpreter._advance_pointer()
+        assert interpreter._pointer == PointerVector([0, 0])
+
+        interpreter._pointer = PointerVector([0, 0])
+        assert interpreter._advance_pointer()
+        assert interpreter._pointer == PointerVector([1])
+
+    def test_advance_pointer_backtrack_from_nested_end(self):
+        @NodeDecorator()
+        def simple_node():
+            return "hello"
+
+        rendered = NodeCompose(NodeCompose(simple_node)).render()
+        interpreter = WorkflowInterpreter(rendered)
+        interpreter._pointer = PointerVector([0, 0])
+
+        assert not interpreter._advance_pointer()
