Update docs and API

[JohnRichard4096]

Summary by Sourcery

Document and enable safe sharing of SuspendObjectStream across interpreters using the CLCA concurrency pattern, and clean up deprecated runtime API.

Enhancements:

• Change child WorkflowInterpreter instances to reuse the parent's object_io stream by default instead of creating a new SuspendObjectStream.
• Remove the deprecated _advance_pointer compatibility property from the workflow runtime API.

Documentation:

• Document SuspendObjectStream concurrency safety guarantees and the CLCA (Cross Loop Callback-Allocate) pattern in both English and Chinese references and guides.
• Add a new CLCA design pattern practice guide in English and Chinese and link it from the docs navigation and related runtime/subgraph isolation documentation.

[sourcery-ai]

Reviewer's Guide

Makes SuspendObjectStream shareable and documented as concurrency-safe via the CLCA pattern, updates fork_interpreter to reuse the parent object_io by default, removes a deprecated pointer-advancing alias, and adds English/Chinese documentation pages and navigation entries for the CLCA design pattern and updated runtime semantics.

Sequence diagram for fork_interpreter shared SuspendObjectStream behavior

sequenceDiagram
    participant Parent as WorkflowInterpreter_parent
    participant Child as WorkflowInterpreter_child
    participant Stream as SuspendObjectStream

    Parent->>Parent: fork_interpreter(compose, middleware, object_io=None)
    alt object_io is None
        Parent->>Stream: use Parent.object_io
        Parent->>Child: __init__(compose, object_io=Parent.object_io, exception_ignored=Parent._exc_ignored, middleware=mdw, extra_args=Parent._ava_args[1:])
    else object_io is provided
        Parent->>Child: __init__(compose, object_io=object_io, exception_ignored=Parent._exc_ignored, middleware=mdw, extra_args=Parent._ava_args[1:])
    end
    Note over Parent,Child: Parent and child now share the same SuspendObjectStream when object_io is None

Loading

File-Level Changes

Change	Details	Files
Change fork_interpreter to share the existing object_io stream by default and update its documentation.	Update fork_interpreter docstring to describe SuspendObjectStream as thread-safe and shareable via CLCA. Change default child interpreter construction to use the parent object_io when no explicit object_io is provided. Clarify in docs that object_io defaults to sharing the parent stream instead of creating a new one in both English and Chinese runtime and practice guides.	src/amrita_sense/runtime/workflow.py docs/guide/practice/subgraph-isolation.md docs/reference/api/runtime.md docs/zh/guide/practice/subgraph-isolation.md docs/zh/reference/api/runtime.md
Document SuspendObjectStream as concurrency-safe and explain the CLCA signal design pattern.	Add a concurrency safety section to the SuspendObjectStream API docs describing CLCA and cross-thread/loop safety. Add equivalent concurrency safety documentation to the Chinese SuspendObjectStream API docs. Introduce new CLCA design pattern practice guides in both English and Chinese with detailed explanation and examples. Expose the new CLCA design pattern guides in the VitePress sidebar for both English and Chinese navigation trees.	docs/reference/api/suspend-object-stream.md docs/zh/reference/api/suspend-object-stream.md docs/guide/practice/clca-design-pattern.md docs/zh/guide/practice/clca-design-pattern.md docs/.vitepress/config.mts
Remove a deprecated alias for advance_pointer from the workflow runtime.	Delete the deprecated _advance_pointer property that proxied to advance_pointer, as announced for removal in v0.3.0.	src/amrita_sense/runtime/workflow.py

---

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.

[cloudflare-workers-and-pages]

Deploying amritasense with    Cloudflare Pages

Latest commit:	c87b042
Status:	✅  Deploy successful!
Preview URL:	https://c2947ccf.amritasense.pages.dev
Branch Preview URL:	https://chore-ref.amritasense.pages.dev

View logs

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• In the CheckpointSignal example, resume() uses with self._lock: on an aiologic.Lock, which is an async lock; this should be made async def resume(...) with an async with self._lock: (or otherwise use the correct locking API) so the sample code is runnable and consistent with the Signal example.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the `CheckpointSignal` example, `resume()` uses `with self._lock:` on an `aiologic.Lock`, which is an async lock; this should be made `async def resume(...)` with an `async with self._lock:` (or otherwise use the correct locking API) so the sample code is runnable and consistent with the `Signal` example.

## Individual Comments

### Comment 1
<location path="src/amrita_sense/runtime/workflow.py" line_range="271" />
<code_context>
             middleware (Callable[[WorkflowInterpreter], Awaitable[Any]] | None | object): The middleware to be used for the sub-interpreter.
                 If UNSET, it will use the same middleware as the parent. If None, it will not use any middleware.
-            object_io (io_T | None): The object I/O stream for the sub-interpreter. If None, it will create a new SuspendObjectStream.
+            object_io (io_T | None): The object I/O stream for the sub-interpreter. If None, it will be set to a shared object stream.

         Returns:
</code_context>
<issue_to_address>
**issue:** Docstring description of `object_io=None` behavior may not match actual implementation and supported types.

Given the implementation `object_io or self.object_io`:
- If `self.object_io` is not a shared `SuspendObjectStream` (or otherwise safely shareable), it will still be reused.
- If both `object_io` and `self.object_io` are `None`, nothing is allocated.

To avoid misleading callers, the docstring should clarify that the parent’s `object_io` is reused, and that safe sharing is only guaranteed for `SuspendObjectStream` (or an explicitly supported subset), rather than implying a new shared stream is always set up.
</issue_to_address>

### Comment 2
<location path="docs/zh/guide/practice/clca-design-pattern.md" line_range="133" />
<code_context>
+- **一次唤醒全部**：`signal()` 完成共享 `Future`，触发所有已注册的回调，全部等待者同时被唤醒。
+- **跨循环安全**：`aiologic.Lock` 保护所有共享状态的读写，每个协程最终 `await` 的是自己所在事件循环内的 `Future`，天然避免了跨循环等待问题。
+
+## 实践二：CheckpointSignal —— 外设式检查点挂起
+
+时序图：
</code_context>
<issue_to_address>
**issue (typo):** “外设式”看起来像是笔误，建议改为“外部式”以与上下文和英文版保持一致。

前文写的是“当控制权在外部时”，英文小节标题也是“External Checkpoint Suspend”。“外设式”一般指硬件外设，语义不符，建议改为“外部式检查点挂起”以避免歧义。

```suggestion
## 实践二：CheckpointSignal —— 外部式检查点挂起
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[x42005e1f]

As I see it, clca-design-pattern.md describes the primitives that already exist in aiologic (aiologic.Event/aiologic.lowlevel.Event/aiologic.lowlevel.Waiter). My library provides not just locks, but a complete set of primitives, so reinventing the wheel like this seems questionable. CheckpointSignal can also be implemented just via aiologic.Condition.