Add native control-flow instructions and BREAK_LOOP support

[JohnRichard4096]

Summary by Sourcery

Introduce native fast-path control-flow instructions and enhance interpreter utilities, weak LRU cache behavior, and documentation for advanced workflow semantics.

New Features:

• Add native control-flow instruction set (NATIVE_IF, NATIVE_WHILE, NATIVE_DO, BREAK_LOOP) based on PUSH/JMP/RET_FAR for low-overhead branching and looping.
• Expose cacheable dependency factories via Depends(..., cacheable=True) for DI and matcher usage.
• Extend WorkflowInterpreter.fork_interpreter to support overriding and merging of available args/kwargs for sub-interpreters.

Enhancements:

• Refine WeakValueLRUCache eviction semantics for loose/normal modes, zero capacity, and expiration behavior, and document its intended usage patterns.
• Tighten type handling and error messaging in fun_typing.sign_func and related dependency metadata structures.
• Improve debugger step helper comments and demo scripts with clearer section markers and examples.
• Mark deprecated WorkflowInterpreter address lookup helpers with explicit DeprecationWarning categories for clearer signaling.

Build:

• Bump project version to 0.5.1 and refresh lock metadata to reflect the new release.

Documentation:

• Substantially expand exception system, core node, self-compile instruction, and addressing model documentation, including exception hierarchy and design principles.
• Add English and Chinese guides for native control flow and native built-in instructions, and cross-link them from introductions and flow control concepts.
• Document InterpreterContext, safe runtime integration via POINTER_DEPENDS, and advanced GOTO/CALL and Bubble addressing behaviors.
• Polish documentation navigation, wording, and theme variables in both English and Chinese, including removal of placeholder items.

Tests:

• Add comprehensive unit tests for WeakValueLRUCache eviction edge cases in loose/normal modes and capacity resizing.
• Add tests for native IF/WHILE/DO instructions and BREAK_LOOP semantics, covering single-node and bubble bodies and loop continuation behavior.
• Extend existing FuncBlock tests with clearer structure markers while preserving coverage.

[JohnRichard4096]

@sourcery-ai title

[sourcery-ai]

Reviewer's Guide

Introduces a new native control-flow instruction set (NATIVE_IF / NATIVE_WHILE / NATIVE_DO / BREAK_LOOP) with supporting runtime nodes, tests, and docs; refines WeakValueLRUCache eviction semantics and adds edge-case coverage; extends dependency injection and interpreter for cacheable dependencies and argument overriding; and updates exception/runtime/node/self-compile documentation plus site navigation for v0.5.1.

File-Level Changes

Change	Details	Files
Add native control-flow instructions (NATIVE_IF, NATIVE_WHILE, NATIVE_DO, BREAK_LOOP) with jump/RET_FAR-based implementations, demos, and tests.	Implement core native control-flow nodes (NativeIfJumpNode, NativeWhileNode, NativeDoWhileNode, NativeBubbleEnterNode) that operate directly on the interpreter pointer and call stack using PUSH/JMP/RET_FAR patterns. Provide high-level SelfCompileInstruction wrappers NATIVE_IF, NATIVE_WHILE, and NATIVE_DO that expand into optimized NodeCompose layouts for single-node or bubble bodies, including RET_FAR insertion and merge/exit points. Introduce BREAK_LOOP as a singleton BaseNode that pops the loop return address and jumps to the parent bubble’s sentinel NOP to terminate native loops cleanly. Expose the new native instructions from the instructions package, add a demo script illustrating their usage, and create comprehensive unit tests for native branching, looping, and BREAK_LOOP behavior. Document native instructions and control flow in new English and Chinese guide pages and cross-link them from introduction, key-features, advanced, and flow-control docs.	src/amrita_sense/instructions/native/__init__.py src/amrita_sense/instructions/native/_core.py src/amrita_sense/instructions/native/if_native.py src/amrita_sense/instructions/native/while_native.py src/amrita_sense/instructions/native/do_native.py src/amrita_sense/instructions/native/break_loop.py src/amrita_sense/instructions/__init__.py demos/21_native_if.py tests/test_native_instructions.py tests/test_native_break_loop.py docs/guide/advanced/native_control_flow.md docs/guide/advanced/built-in_instruction_set/native_instructions.md docs/zh/guide/advanced/native_control_flow.md docs/zh/guide/advanced/built-in_instruction_set/native_instructions.md docs/guide/concepts/flow_control.md docs/zh/guide/concepts/flow_control.md docs/guide/introduction/index.md docs/guide/introduction/key-features.md docs/zh/guide/introduction/index.md docs/zh/guide/introduction/key-features.md docs/.vitepress/config.mts
Tighten WeakValueLRUCache eviction semantics and add boundary tests and improved documentation.	Refine WeakValueLRUCache.put logic to compute should_expire_count once, iterate over a bounded number of entries, treat loose_mode differently for alive vs expired refs, and avoid infinite loops when capacity is exceeded with all entries alive. Clarify expire() behavior by defaulting length to 20% of current cache size and simplifying expired-key scanning and removal. Augment docstring with a typical lock-pool usage example and warnings about unsuitability for persistent storage and for immutable objects. Add extensive boundary tests for put() covering loose vs normal modes, all-expired vs partially expired entries, zero capacity behavior, mixed alive/expired scenarios, and resize-induced eviction. Ensure tests assert both size and get() semantics after eviction under various edge conditions.	src/amrita_sense/weakcache.py tests/test_weakcache.py
Extend dependency injection and function typing to support cacheable dependencies and stricter annotation handling.	Add a cacheable flag and slots to DependsFactory, expose a cacheable property, and extend the Depends() helper to accept and pass this flag, updating docstrings around caching and DI behavior (including None-return semantics and DB session caveats). Simplify TYPE_CHECKING handling in fun_typing, remove the runtime DependsFactory stub, and tighten DependencyMeta typing to reference the real DependsFactory and Matcher instead of string-typed forward references. Improve the error message for unresolved annotations to mention global-scope imports instead of TYPE_CHECKING-only blocks and clarify the guidance around future.annotations.	src/amrita_sense/hook/matcher.py src/amrita_sense/hook/fun_typing.py docs/reference/api/self-compile.md docs/zh/guide/advanced/custom_node.md
Enhance WorkflowInterpreter for argument overriding on fork and improve deprecation warnings, stepping, and docs for runtime behavior.	Extend WorkflowInterpreter.fork_interpreter to accept ava_args and ava_kwargs, merging them with the parent interpreter’s arguments (excluding self) before passing into the new interpreter’s extra_args/extra_kwargs. Update deprecated find_addr and find_addr_alias to specify DeprecationWarning category in the decorator usage. Adjust debugger _step_one to use clearer comment-style section markers and keep behavior in sync with run_step_by preamble, suspension check, pointer initialization, and single-node execution under the interpret lock. Clarify exec_and_interrupt docs around InterruptNotice handling to log pointer and message and explicitly state that interrupt is termination, not suspension, requiring re-render/recreate to re-run.	src/amrita_sense/runtime/workflow.py src/amrita_sense/debugger/step.py docs/guide/concepts/exec_and_interrupt.md docs/zh/reference/api/types.md
Improve exception, node, and self-compile documentation for clarity, hierarchy, and advanced addressing concepts.	Rewrite exceptions reference to document each exception class with code snippets, trigger scenarios, interpreter response, and an explicit exception hierarchy diagram and design principles, including BaseException vs Exception inheriting semantics. Expand core node docs to detail BaseNode attributes, methods, slots usage, Node/NodeCompose/NodeComposeRendered behaviors, compilation process, alias mapping, and immutability guarantees. Greatly extend self-compile instruction docs to describe the SelfCompileInstruction interface, built-in instruction expansions (IF, WHILE, DO, TRY, subprograms), custom instruction design, compile-time vs runtime behavior, and how CALL differs from self-compiling instructions. Elaborate advanced locating and address-space guide with GOTO validation, jump-marker mechanics, CALL semantics, PointerVector/Bubble scoping, near vs far addressing, and best practices for alias usage and scope isolation.	docs/reference/api/exceptions.md docs/reference/api/core-nodes.md docs/reference/api/self-compile.md docs/guide/advanced/locating_and_space.md
Polish docs site, themes, demos, and tests for consistency with new features and naming.	Add navigation items for native control flow and native instructions in both English and Chinese VitePress config, and remove placeholder "Under Construction" menu entries. Normalize CSS variable capitalization for tip/warning colors in the docs theme. Retag comment headings in multiple demo and test files to use consistent markdown-like section markers (###) instead of mixed comment styles. Bump project version from 0.5.0 to 0.5.1 to reflect the new native instruction set and documentation updates, and update the lockfile accordingly.	docs/.vitepress/config.mts docs/.vitepress/theme/var.css demos/16_subgraph_isolation.py demos/20_batch_run.py tests/test_func_block.py pyproject.toml uv.lock

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @JohnRichard4096, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery