core(reply): rebuild from kameo reference — Reply + Delegated/Forwarded + ReplySender

[joeldsouzax]

Part of the core-rebuild epic — follows the shared rigor contract there.

Component

src/reply.rs (~1,048 LOC). Reply, DelegatedReply, ForwardedReply, ReplySender, ReplyError.

Learning & discussion

The reply channel is an in-process oneshot — no serialization locally. Delegated/forwarded replies let another actor answer on this actor's behalf. Dropping a ReplySender without replying must surface an error to the caller, never hang.

Existing crates

tokio::sync::oneshot for the reply channel — evaluate.

Research — best algorithm/approach

Reply-channel lifecycle; delegated/forwarded-reply patterns; drop-without-reply semantics.

Testing — hard as fuck

Lifecycle (drop ReplySender → caller gets ReplyError, not a hang), sequence, linearizability (concurrent ask + reply). DST over reply/drop races. Mutation: cargo-mutants, zero survivors.

[joeldsouzax]

Knock-on from #114 — typed reply port, reply erasure removed

The message-model finalization (#114) fixes the reply shape:

• Reply = typed oneshot::Sender<Reply> embedded in the requesting Msg variant (ractor RpcReplyPort pattern). ask costs exactly 1 allocation (the oneshot Arc<Inner>), the irreducible floor for a typed async reply, and stays fully typed end-to-end.
• Removes BoxReplySender / Box<dyn Any> reply-payload erasure. kameo erases the reply payload to Box<dyn Any> (re-typed caller-side via Reply::downcast_ok) only because its single shared Signal<A> envelope can't name a per-M sender type. A per-variant reply port names the reply type directly, so there is nothing to erase.
• Reply / Delegated / Forwarded / ReplySender retype to typed ports. 3 of 4 surveyed frameworks keep the reply fully typed (ractor RpcReplyPort, xtra catty, actix oneshot<M::Result>); kameo is the erased outlier.

Cross-links: message model #114 · trait/handle #116 · mailbox #112.

[joeldsouzax]

Revised by the adversarial review (#122)

Reply-port type was underspecified — it mixed ractor's embedded-port model with actix's loop-routing model, which can't both hold (once the port is moved into the Msg variant and consumed by handle, the loop can't see the reply or route the error).

Corrected: the embedded reply port is oneshot::Sender<Result<Reply, E>> (not Reply). The handler sends exactly one Ok(reply) / Err(e) through it — that's the asker's domain error. The handler's -> Result<(), Self::Error> return is reserved for supervision, not the reply. Ask-side mapping: Ok(Ok(r))→Ok(r) · Ok(Err(e))→HandlerError(e) · Err(RecvError)→InterruptedBeforeReply (#113).

[joeldsouzax]

🧪 Test cases to write first (TDD — implement with this card)

• @bug ask_handler_error_reaches_caller_typed (sequence) — handler sends Err(DomainErr) through the reply port; caller ask MUST get Err(SendError::HandlerError(DomainErr)) (typed, not erased). Fails if the port is oneshot<Reply> instead of oneshot<Result<Reply, E>>. (Ref epic: rebuild the runtime core part-by-part (kameo = reference oracle) #122-refactor: ActorId identity — libp2p PeerId to Zenoh key-expr #2.)
• ask_ok_reply_reaches_caller (sequence) — handler sends Ok(reply) → caller gets Ok(reply).
• reply_port_single_send (defensive) — handler must send exactly one Ok/Err; a second send is a no-op/err, not a panic.
• tell_has_no_reply_port (defensive) — a tell variant carries no reply port; E = Infallible for tell.

[joeldsouzax]

Re-scope (design decision, approved)

Building #115 as the typed reply-channel primitive only; DelegatedReply/ForwardedReply move to the cards that give them meaning.

Why. In the reference, DelegatedReply/ForwardedReply are produced solely by Context::reply_sender()/reply()/spawn()/forward() — and forward needs ActorRef<B> + Message<M>. None of that exists until #116 (actor/Context/loop), #117 (ActorRef), #118 (request). Shipping them now would be dead-until-later types tested only for construction/Debug — violating YAGNI (CLAUDE rule 4, 'add at the second concrete use') and 'test the real SUT' (rule 8). They land wired + tested with their machinery.

#115 delivers (all standalone-testable):

• ReplySender<R, E> over oneshot::Sender<Result<R, E>> — typed, no Box<dyn Any> erasure.
• reply_channel::<R, E>() constructor pairing sender + receiver.
• Single-send + drop-without-reply semantics.
• Ask-side result mapping into core(error): rebuild from kameo reference — typed error domains #113's AskError: Ok(Ok(r))→Ok(r) · Ok(Err(e))→Handler(e) · Err(RecvError)→Interrupted.

Also decided: the reference Reply trait (its only job was Box<dyn Any> erasure — ~40 std impls + derive) is dropped. With a typed port there is nothing to erase; any R: Send + 'static is a reply.

The four card test cases (ask_ok_reply_reaches_caller, @bug ask_handler_error_reaches_caller_typed, reply_port_single_send, tell_has_no_reply_port) all sit on the primitive and are written first (TDD).