[Feature] Per-actor message batching (throughput) in ActorCell.run

[pathosDev]

Rationale

ActorCell.run() drains all system messages, then dequeues exactly one user message and reschedules (src/internal/ActorCell.ts:~403 plus the finally re-schedule). With the default immediate dispatcher every user message pays a full setImmediate round-trip. Akka processes throughput messages per scheduling slot for exactly this reason; ThroughputDispatcher(16) only batches work units across actors — each unit is still a single message.

Scope

• Process up to throughput-per-actor user messages per execute() slot (HOCON actor-ts.dispatcher.throughput-per-actor, default ~16, optional time budget), then yield.
• Preserve: system-messages-first ordering, the throttle gate (Token-bucket rate limiting per actor #83), suspend semantics, per-actor dispatcher override via Props config.
• reference.conf + ConfigKeys entry.

Example configuration:

actor-ts.dispatcher {
  default = "immediate"
  throughput-per-actor = 16    # messages per scheduling slot (previously implicitly 1)
}

Documentation

• Dispatcher docs (EN + DE) incl. the fairness trade-off (large batches can starve I/O).
• CHANGELOG entry; HOCON key reference.

Acceptance

• tell/ask throughput benchmarks improve ≥ 2× under the default dispatcher; become/unbecome bench flat; ordering + throttle tests green.

Relates

Improvement program M2. #27, #83; pairs with the ring-buffer mailbox issue.

[pathosDev]

Re-derived independently in the production-readiness review tracked in #913, with a measurement that sharpens the scope here.

The one-message-per-slot ceiling was measured against a competing setImmediate ticker: 1.00 event-loop turns per message for ImmediateDispatcher — and also 1.00 for ThroughputDispatcher(16) and (256). The documented throughput knob is a no-op for a single busy actor, because run() is async and suspends at its first await, so drain()'s synchronous while (processed < throughput) loop has already exited before the cell re-queues itself.

End-to-end effect on this machine, with the mailbox raised so nothing is dropped:

default (Immediate, bounded 10k)   sent=50000 processed=  9999      90744 msg/s   ← measures drops
capacity 1M (no loss)              sent=50000 processed= 50000     269611 msg/s
+ ThroughputDispatcher(64)         sent=50000 processed= 50000     279715 msg/s   ← +4 %
+ MicrotaskDispatcher              sent=50000 processed= 50000     658585 msg/s   ← starves I/O

Raw setImmediate on the same box is 760 156 ticks/s, so that is the architectural ceiling until batching moves inside the cell. Two implications for this issue: the batch loop must live in run() rather than in a dispatcher, and ThroughputDispatcher should probably be documented as "batches across actors" or removed, because its name currently promises the thing this issue exists to add.

This issue is labelled production-goal. It is also filed as enhancement, but a documented knob that does nothing is a defect — bug added.