core(request): rebuild from kameo reference — ask/tell builders

[joeldsouzax]

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

Component

src/request.rs, src/request/ask.rs, src/request/tell.rs (~2,583 LOC). ask (wait for reply) vs tell (fire-and-forget), timeouts, mailbox-full handling, blocking/try variants.

Learning & discussion

ask correlates a reply over the in-process oneshot; tell just enqueues. Capacity hit and timeout are Result, never panic (rule 4). The builder ergonomics decide the whole public send API.

Existing crates

bon for the request builders (#54) — typed, ergonomic builders over the ask/tell option matrix.

Research — best algorithm/approach

Builder ergonomics (typestate vs bon); ask/tell/timeout semantics; how backpressure is surfaced to the caller.

Testing — hard as fuck

Boundary (timeout fires; mailbox full → Result, not panic; zero-capacity), sequence, linearizability (concurrent ask/tell under contention). DST over timeout/full races. Mutation: cargo-mutants, zero survivors.

Absorbs

#54 (bon request builders).

[joeldsouzax]

FINALIZED — request builders: ask / tell over the typed message model

Reconciled with the message model (#114), typed reply (#115), and error model (#113). Absorbs #54.

Surface

actor_ref.tell(msg)                       // -> Result<(), SendError<M, Infallible>>
actor_ref.tell(msg).try_send()            // non-blocking: MailboxFull(M) if bounded mailbox full
actor_ref.ask(req).await                  // -> Result<Reply, SendError<M, E>>
actor_ref.ask(req).timeout(d).await       // adds SendError::Timeout(Some(req))

• tell — moves Signal::Message(msg) into the mpsc<Signal<A>> → 0 heap alloc (core(message): rebuild from kameo reference — Message trait + Context dispatch #114). Bounded mailbox: send().await backpressures, or try_send() returns MailboxFull(M) (retryable, msg handed back). Reaped target → ActorNotAlive(M).
• ask — embeds a typed oneshot::Sender<Reply> in the request's Msg variant (RpcReplyPort, core(reply): rebuild from kameo reference — Reply + Delegated/Forwarded + ReplySender #115) → 1 alloc (the oneshot); awaits the receiver. HandlerError(E) if the handler returned Self::Error (incl. nexus Conflict); Timeout(Option<M>) via the builder; ActorNotAlive if reaped.
• No pre-send liveness check — TOCTOU-wrong (core(actor_ref): rebuild from kameo reference — ActorRef / Weak / Recipient #117). Send-and-observe: SendError is the death signal (a reaped actor's dropped receiver → ActorNotAlive).
• Backpressure is a builder choice: send().await (wait) vs try_send() (→ MailboxFull). Mailbox strategy (Fifo / Ring keep-latest, feat: mailbox strategies via channel handlers (RingChannel keep-latest vs FifoChannel) #19) is chosen at spawn.

Two-tier

Local ask/tell = the above (typed sender in ActorRef<A>). Remote = Zenoh get/put over the serialized Command (#114 boundary) — same builder surface, different backend; the caller doesn't branch on locality.

Cross-links: error model #113 (SendError) · message/reply #114/#115 · mailbox strategy #19 · ref/death #117 · cancellation #55.

[joeldsouzax]

Revised by the adversarial review (#122)

Decision owed — bounded-mailbox request-cycle deadlock (#4, verified real, all 4 Coffman conditions). A asks B while B asks A, both mailboxes full → both park on send().await → hang. You cannot make this structurally impossible while a handler may synchronously send().await.

• Prevent (CPS): never block the message loop — outbound asks are fire-and-forget, the reply returns as a new self-message (continuation). Removes hold-and-wait; the actor-native (Erlang/ractor) answer. Cost: continuation-style handlers.
• Detect: try_send+MailboxFull(M) fallback and/or ask-timeout. What actix ships; not deadlock-free.

Also: the ask-side reply mapping is Ok(Ok)→Ok / Ok(Err(e))→HandlerError(e) / Err(RecvError)→InterruptedBeforeReply (see #113/#115).

[joeldsouzax]

DECISION — deadlock posture (#4): handler-no-block discipline + timeout backstop

The bounded-mailbox cycle deadlock (#122 #4) can't be made structurally impossible while a handler may synchronously send().await. Resolved, principled by the event-sourced/DDD model rather than picking one raw mechanism:

1. Handlers do NOT block on other actors — the structural prevention. A handle is a command→events→return function (nexus contract #59); cross-aggregate coordination goes through sagas / the event log (async), not synchronous ask. A handler triggers other actors with tell (fire-and-forget) or by emitting an event a saga reacts to — it never ask().awaits another actor mid-handle. Rationale beyond deadlock: a synchronous cross-aggregate call holds the single-writer consistency boundary open across an external call (widens conflict windows) and is a DDD anti-pattern. Because idiomatic aggregate code never forms handler→handler cycles, the deadlock cannot arise there. Documented on the handler contract (not compiler-enforced).

2. Blocking ask is allowed OUTSIDE handlers (external clients, the saga runner, infra actors) with a default, builder-overridable timeout (Erlang gen_server:call / ractor precedent, ~5s default). Any accidental cycle resolves as SendError::Timeout rather than hanging. Infinite-timeout ask is an explicit, discouraged opt-in.

3. try_send + MailboxFull(M) for non-blocking, backpressure-aware sends.

Net: structural prevention in idiomatic aggregate code (handlers don't block), timeout detection where blocking is legitimate. We do NOT impose full CPS on external asks — the cycle only forms from handler→handler blocking, which the domain model already forbids.

Cross-links: handler contract #116/#114 · error model (Timeout/MailboxFull) #113 · saga-driven cross-aggregate coordination + nexus contract #59.

[joeldsouzax]

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

• @bug ask_actor_dies_mid_handle_maps_interrupted (sequence/lifecycle) — actor accepts an ask, then panics/is-killed before replying (reply port dropped unsent). Caller MUST get Err(SendError::InterruptedBeforeReply) — NOT ActorNotAlive (was alive at accept) and NOT Timeout (no deadline elapsed). Fails if the variant is missing or mapped wrong. (Ref epic: rebuild the runtime core part-by-part (kameo = reference oracle) #122-feat: replace DHT registry with key-expr discovery #3.)
• ask_times_out_when_target_saturated (defensive/liveness) — fill the target's bounded mailbox; ask with a short timeout resolves Err(Timeout) within the bound, no hang. (Ref epic: rebuild the runtime core part-by-part (kameo = reference oracle) #122-feat: messaging over Zenoh query/reply #4 detection.)
• try_send_full_returns_mailbox_full_with_msg (defensive) — try_send to a full bounded mailbox → MailboxFull(M), message recovered.
• tell_is_zero_alloc / ask_is_one_alloc (property/bench) — allocation-count assertions on the hot paths (the un-templated claim — measure). (Ref epic: rebuild the runtime core part-by-part (kameo = reference oracle) #122-feat: wildcard/hierarchical key-expr group addressing #11 / core(message): rebuild from kameo reference — Message trait + Context dispatch #114.)
• DST: cyclic_topology_never_deadlocks (linearizability/DST, seeded) — a saturated multi-actor topology where handlers use the fire-and-forget + self-continuation discipline; assert every request eventually resolves or times out, no permanent hang. Encodes the feat: messaging over Zenoh query/reply #4 decision (handlers don't block).