Stage Wrapper on Spot¶
Spot And Actor topic index · Spec table of contents · Previous: 06. Spot Address Messaging · Next: 08. Spot/Actor Routing
Defines the execution boundary an application's domain wrapper must keep when building a higher-level execution model such as room/stage/zone on top of the framework's public Spot contract — a logical instance with an address and state, reachable by the same global Spot ID even when its executing node changes.
1. Stage Wrapper Overview¶
A Stage wrapper must safely maintain the state owned by a Spot while preserving the Spot/Actor/timer execution boundary that matches the selected User Spot execution mode.
The framework doesn't provide a separate Stage runtime or a common Stage base type. The application's domain wrapper composes the Spot's public registration/messaging/timer/ lifecycle surface. Each language's wrapper shape is determined by that language's public interface document.
2. Responsibility Boundary¶
| Responsibility | Owner |
|---|---|
| Spot identity, create/close, and the application turn | Owned by the framework Spot runtime. |
| Spot direct and Logical Multicast (a method of delivering one message to multiple Spots of the same Channel by ChannelName and topic) dispatch | Owned by the framework Spot runtime. |
| Timer admission and callback turn | Owned by the framework Spot runtime. |
| Actor queue and Actor business handler | Owned by the framework Actor runtime. |
| Actor join/leave and lifecycle control | Owned by the Spot/Actor-dedicated queue the framework uses to process lifecycle work. |
| Admission rights, stage state, membership policy, and broadcast content | Owned by the Stage wrapper or application. |
| The policy mapping a domain key to a global Spot ID | Owned by the Stage wrapper and application domain store. |
A Stage wrapper doesn't expose transport RID, endpoint, internal queue, native timer handle, or message storage reference on the public surface. This is because the wrapper's public surface must consist only of the framework's public Spot/Actor/timer/ location surface.
3. Preserving the Spot Turn¶
A callback that reads or changes state owned by the Stage must run on the target Spot's application turn — the Spot turn, the unit in which one Spot callback holds the application queue's execution gate to run. The following callbacks are subject to this rule.
- Spot direct handler
- Logical Multicast subscription handler
- Spot timer callback
- Actor join/leave and lifecycle control callback
- A domain operation the Stage wrapper explicitly submitted to the Spot
Execution-mode registration follows the Spot model. Execution contract §2 owns gates, turns, and continuations; §3 owns Yield and Actor claims.
- A wrapper does not change this execution contract through a separate scheduler or lock rule. Wrapping a Framework callback must preserve the same execution order.
- The application owns synchronization of shared Stage state in
PerActor. Callbacks on different gates permitted by the execution contract can access the same domain state.
4. Actor Boundary¶
Even if an Actor joins a Spot serving as a Stage, the Actor's business payload is still delivered directly to the Actor queue. Actor payload isn't converted into a Spot callback or put on the Spot application queue. Consequently, an Actor handler doesn't directly reference the Stage's mutable state.
For an Actor to change Stage state, it submits an explicit send/request to the Stage Spot. That handler makes membership — which Stage Spot the Actor currently belongs to — as well as score, world state, and broadcast decisions on the Spot turn.
The framework processes an Actor's join, leave, relocation, and lifecycle notification on a dedicated queue separate from business messages. This queue doesn't run the Actor's regular business handler, and doesn't convert business payload into a lifecycle callback either. The detailed Actor queue and lifecycle handling contract is owned by Actor Model.
5. Timer and Yield¶
Stage timer registration and tick processing follow the public Spot timer contract.
- Spot shutdown closes admission of new timer ticks. The order between already-accepted ticks and the shutdown callback is determined by the Spot lifecycle rule.
- Fixed-rate, delay, catch-up, and overrun options are expressed through each language's public timer contract.
- The wrapper doesn't expose a native handle or scheduler thread to the application.
Yield availability and reentrancy errors follow
execution contract §16.
The wrapper defines no separate Yield or Actor-claim rule.
Even after a host Relocate starts, a Stage Spot that hasn't yet obtained execution
rights to start relocation keeps processing its existing message and timer turns. The
internal notification the framework uses to announce relocation readiness isn't an
application event, so it doesn't run a Stage callback.
After execution rights are obtained and new turn admission is closed, timer ticks not yet
run and timer registration information are included in the relocation payload. Since the
target framework automatically restores these, the Stage wrapper's Restore doesn't
re-register the same timer.
6. Creation and Membership¶
The Stage wrapper passes a stable type and a domain creation payload to the User Spot manager's explicit Create/GetOrCreate, and builds the initial Stage state inside the creation callback. Even if multiple nodes try to create the same Spot concurrently, the Framework only runs the one factory that obtained creation authority. The condition for allowing new work and the business state restored after reactivation are decided by domain rules.
Actor join checks the Stage membership policy on the framework's lifecycle-dedicated queue. If the join succeeds, the Actor's current Spot location and the member state owned by the Stage are updated together. The method for confirming a concurrent change as one, and the message admission boundary during relocation, are owned by Spot And Actor Membership.
A Stage-wide notification uses whichever path matches its meaning.
- Use Logical Multicast to notify multiple Spots of the same ChannelName.
- To notify based on one Stage's member state, pick the target Actor or bound session on the Spot turn and submit an explicit message.
Logical Multicast isn't used as the durable source of the Stage member list.
7. Location and Lifetime¶
An external service obtains a global Spot ID from a
domain key and sends a message to the Stage Spot. When closing that incarnation or
displaying it as operational information, use the SpotRef the manager lookup returned.
The owner RID and endpoint aren't stored in wrapper state. The meaning of location updates and
stale routes is defined by
Spot Address Messaging.
Stage shutdown closes new application admission and new joins, and finishes cleanup of already-accepted Spot turns and membership within the drain deadline. Timers, subscriptions, and direct messages after shutdown don't create a new Stage callback.
8. Metadata and Observability¶
The Stage wrapper provides the immutable metadata snapshot of the Message Model to the handler as-is, and doesn't interpret the transport frame or storage ownership.
Observability information must distinguish MeshName (the name that identifies one RouteMesh physical connection group), Stage type, Spot turn backlog, timer delay, membership control result, and shutdown state. Stage ID and Actor ID aren't used as metric labels.
9. Implementation and Contract-Test Verification Requirements¶
Confirm the following using only the public surface — the framework's public
Spot/Actor/timer/location surface the Stage wrapper uses, the point at which Yield
returns, and the submit-time error. Each item maps to one contract test.
Spot Turn and Yield
Execution order, continuation, Yield, and reentrancy observations for wrapper callbacks reference execution contract §16.
Actor Boundary
- Actor payload doesn't pass through a Stage Spot callback or the Spot application queue.
- The Actor handler uses an explicit Spot call to change Stage state.
- The framework's Spot-lifecycle-dedicated queue only contains join/leave and lifecycle control, and doesn't include Actor business payload.
Surface Compliance And Shutdown
- The Stage wrapper only uses the framework's public Spot/Actor/timer/location surface.
- No new timer or message callback runs after Spot shutdown.
- A Stage Spot isn't sealed before a relocation permit, and after seal, timer registration and pending ticks are automatically restored on the target.
Spot And Actor topic index · Spec table of contents · Previous: 06. Spot Address Messaging · Next: 08. Spot/Actor Routing