Chore/actor runtime stream async blueprint 20260305#26
Merged
Conversation
- Introduced a comprehensive blueprint for refactoring the actor runtime's stream async capabilities, focusing on unifying request/reply, timeout, and timer functionalities. - Established core architectural decisions, including the use of Orleans native scheduling and the removal of legacy CQRS helpers. - Defined new abstractions and lifecycle management for stream request/reply, ensuring robust governance and observability. - Documented migration work packages and testing strategies to facilitate implementation and validation of the new architecture.
- Added new interfaces and classes for asynchronous scheduling, including `IActorRuntimeAsyncScheduler`, `RuntimeTimeoutRequest`, and `RuntimeTimerRequest`. - Introduced methods for scheduling timeouts and timers, along with cancellation support in `IEventHandlerContext`. - Enhanced the `InMemoryActorRuntimeAsyncScheduler` and `OrleansActorRuntimeAsyncScheduler` to manage scheduled callbacks effectively. - Updated dependency injection to register the new async scheduler implementations and related services. - Documented architectural decisions and migration strategies for integrating the new async capabilities into the existing actor runtime.
- Introduced a new callback scheduling framework, replacing the previous async scheduling interfaces with `IActorRuntimeCallbackScheduler` and related classes. - Unified request/reply, timeout, and timer functionalities under a cohesive architecture, enhancing the actor runtime's scheduling capabilities. - Removed legacy async components and ensured backward compatibility is not maintained, aligning with the zero-compatibility design. - Updated dependency injection to register new callback scheduler implementations for both in-memory and Orleans contexts. - Documented architectural decisions, migration strategies, and testing requirements to support the new callback scheduling model.
…cution semantics - Updated the actor runtime callback scheduling framework to support a volatile execution model, ensuring that runtime coordination does not persist in business actor state. - Introduced new metadata structures for callback envelopes, enhancing the self-descriptive nature of fired callbacks. - Implemented strict guards and tests to prevent regression to legacy scheduling paths and ensure robust metadata validation. - Removed outdated components and streamlined the callback scheduling process, aligning with the architectural vision of zero-compatibility. - Documented architectural decisions and testing requirements to support the new callback model and its implications for runtime behavior.
…antics - Updated the `IActorRuntimeCallbackScheduler` interface and its implementations to ensure all callbacks are scheduled with durable semantics, removing inline and dedicated options. - Enhanced the `EventHandlerContext` and `GAgentBase` classes to utilize the new durable scheduling methods, improving clarity and consistency in callback handling. - Removed legacy inline callback scheduling components to streamline the architecture and prevent misuse of transient state. - Documented architectural changes and updated dependency injection configurations to reflect the new durable callback model. - Improved metadata validation for scheduled callbacks, ensuring robust handling of callback leases and enhancing overall system reliability.
- Updated the audit documentation to reflect the latest review findings and architectural changes. - Enhanced the assessment criteria and scoring metrics, resulting in an improved score from 68 to 82. - Documented the closure of critical architectural issues while highlighting remaining concerns related to workflow callback handling. - Provided detailed evidence and conclusions regarding the durability of callback semantics and their implications for system reliability. - Emphasized the need for further testing to address outstanding issues before merging the changes.
…vent handling - Updated `HumanInputModule`, `HumanApprovalModule`, `WaitSignalModule`, and `WorkflowLoopModule` to ensure that `run_id` is mandatory for resuming workflows, eliminating fallback mechanisms for missing `run_id`. - Refined event handling logic to improve clarity and reliability, ensuring that pending events are only resolved when valid `run_id` is provided. - Added tests to validate the behavior of modules when `run_id` is missing, confirming that workflows do not resume under ambiguous conditions. - Improved error handling and logging for timeout and retry scenarios, enhancing the robustness of the workflow execution model.
- Revised the audit scorecard document to incorporate insights from the latest review, emphasizing the closure of previously identified issues through destructive refactoring. - Clarified the assessment of workflow callback semantics and their alignment with interaction contracts. - Updated the conclusion to indicate a score of 95/100 (A) and a recommendation for merging based on the reanalysis of the current code state.
…eduler Refactor - Added a new audit scorecard document summarizing the reanalysis of the Foundation Runtime Callback Scheduler, reflecting a significant decline in the score from 95/100 to 67/100 (C) due to unresolved architectural issues. - Highlighted critical problems related to durable callback routing, self callback metadata inheritance, and script definition query persistence across runtime reactivations. - Provided detailed evidence and scoring metrics across multiple dimensions, emphasizing the need for further improvements before merging changes.
…dling - Incremented documentation version to v8 and updated the last modified date. - Enhanced the `ScriptRuntimeGAgent` to support persistent handling of pending definition queries, ensuring robust recovery during runtime reactivations. - Introduced new message types for managing script definition query states, including `PendingScriptDefinitionQueryState`, `ScriptDefinitionQueryQueuedEvent`, and `ScriptDefinitionQueryClearedEvent`. - Refactored callback scheduling in `OrleansActorRuntimeDurableCallbackScheduler` to exclusively utilize reminders, removing legacy timer options and ensuring consistent callback delivery semantics. - Updated tests to validate the new behavior and ensure compliance with the revised architecture.
…ream-async-blueprint-20260305
Contributor
|
eanzhao
added a commit
that referenced
this pull request
May 8, 2026
- #13 (major, arch): /api/oauth/aevatar-client/rebuild now dispatches ProvisionAevatarOAuthClientCommand via IActorDispatchPort.DispatchAsync, matching /unbind. The inline actor.HandleEventAsync was a known CLAUDE.md "投递语义必须 runtime-neutral" violation; aligning the two endpoints removes the inconsistency that any future inbox middleware would silently bypass on rebuild. - #24 (minor, design): callback endpoint accepts ?format=json on the URL to opt back into the {status:"bound", already_bound, display_name} envelope that programmatic CLI/SDK consumers used pre-HTML-render. Default stays HTML for browser callbacks. - #26 (minor, arch): /rebuild now sits behind a RebuildAuthEndpointFilter that enforces the admin-token check before model binding and per-request DI activation kick in. The filter + the inline check in the handler are redundant by design (defense in depth) — the filter rejects unauth posts before deserialization runs, and the handler still validates so hand-rolled tests/integration scenarios cannot bypass. - #28 (minor, design): document the readmodel-deletion contract in the ExternalIdentityBindingProjector header — empty BindingId deletes the document instead of upserting an inactive record; downstream audit consumers must read the committed-event log directly. - #1 + #2 (blocker, arch): no change needed. Earlier commits in this PR already moved /model self-heal to IActorDispatchPort.DispatchAsync and removed the EnsureProjectionForActorAsync call from the slash-command request path. Verified by reading the current handler. - #25 (minor, test): documented in the rebuild handler comment — concurrent /rebuild calls would race on the same actor, but this is operator-grade break-glass and de-duping concurrent rebuilds is out of scope. Build clean (Identity), 34 OAuth-path tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a major architectural refactor to unify and elevate asynchronous stream, timeout, and timer capabilities into the Actor Runtime layer. It establishes new abstractions and contracts for scheduling, callback management, and stream request/reply, and implements these for both Local and Orleans runtimes. The changes also enforce stricter architectural boundaries, improve reliability, and lay the groundwork for future extensibility and governance.
Key changes include:
Architectural Refactoring & Documentation
New Abstractions for Async Scheduling & Callbacks
IActorRuntimeAsyncScheduler,RuntimeTimeoutRequest,RuntimeTimerRequest,RuntimeCallbackLease, and related metadata keys to standardize timeout/timer scheduling and callback management across runtimes. [1] [2] [3] [4] [5]IEventHandlerContextand its implementation to expose methods for scheduling/canceling timeouts and timers, using the new scheduler abstraction. [1] [2] [3]Stream Request/Reply Unification
IStreamRequestReplyClientabstraction to the Foundation, standardizing stream-based request/reply patterns and enabling unified lifecycle management.Dependency Injection & Integration
Orleans Runtime Support
These changes lay the foundation for a robust, unified, and observable async runtime across both Local and Orleans environments, with strong architectural guarantees and extensibility for future actor-based workflows.