[P0-28] Add bounded mailboxes, admission control, and structured overload results #36

New issue

Open

opened 2026-07-22 00:15:32 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-22 00:15:32 +00:00

(Migrated from github.com)

Governance / ARDR state

Research authority: lost-rob0t/starintel-auto-research/roam/research/ardr-issues/ARDR-ISSUE-190-sento-bounded-mailbox-admission.org — READY_FOR_DESIGN
Design authority: lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-043-sento-bounded-admission.org — DESIGN_READY_FOR_OPERATOR_REVIEW
Dependencies: #34/#177 process budget; #35/#188/#189 Sento execution-lane accounting; #37/#182/#183 lifecycle/quiesce ownership
Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL

Exact Sento finding

Current StarIntel pin mdbergmann/cl-gserver@6a510c5b58469e72e6363bd3a6059d80b9a5c320 already has the actor-local primitive we need:

message-box-base accepts max-queue-size;
0/nil selects an unbounded queue;
positive capacity selects queue-bounded;
bounded pushq immediately signals queue-full-error when full;
queued-count exposes current depth;
both pinned (message-box/bt) and dispatcher-backed (message-box/dp) mailboxes inherit this queue selection.

Therefore do not replace Sento's mailbox/queue backend for this P0. Configure the existing bounded queue and add StarIntel admission/result semantics around it.

Critical distinction

Mailbox backlog and dispatcher concurrency are different resources:

mailbox capacity != dispatcher worker count

#35 bounds aggregate Sento execution lanes. This issue bounds queued work and composes that with HTTP, Rabbit, task and publication admission.

Required behavior

Production data-plane actors use explicit positive mailbox capacities or a validated bounded default.
Full mailbox becomes a typed StarIntel overload result, not an uncaught raw queue-full-error and never silent success.
Default policy is reject/reply-busy.
Blocking admission is permitted only with an explicit absolute deadline and waits outside Sento's FIFO primitive.
drop-old is not a default policy; it discards already-accepted work and requires separate workload-specific proof.
Critical health/shutdown/supervision/lease-renewal traffic uses a separate bounded control path rather than queueing behind saturated data FIFO work.
Rabbit prefetch/in-flight derives from actual granted processing capacity plus a bounded per-worker factor; retire hard-coded 200 as independent authority.
HTTP admission occurs before expanding bulk requests into deeper actor/task work.
Task/publish/persistence handoff queues must be bounded; do not merely move the unbounded queue downstream.

Typed overload result

At minimum: boundary/component ID, reason, depth when observable, capacity, policy, optional justified retry-after, correlation/trace ID, timestamp.

Proposed slices — ALL PENDING OPERATOR APPROVAL

Sento mailbox configuration + typed queue-full-error translation.
Explicit reject/reply-busy + deadline-bounded blocking admission API.
Separate control/data admission path proving control responsiveness under saturation.
Rabbit prefetch derivation from real granted processing capacity.
Downstream bounded task/publish queues + pressure diagnostics.

RED-first targets

Capacity-2 actor: after two queued items, third submission must produce typed overload with depth=2/capacity=2 and zero handler invocation for the rejected item.
Same mailbox capacity remains 2 regardless of dispatcher worker count.
Blocking submission without deadline is rejected.
Saturated data mailbox does not block separate control health/stop fixture.
Rabbit fixture with granted worker count 2 no longer uses constant prefetch 200.
Synthetic actor -> task -> publish pipeline proves accepted outstanding work remains bounded at every stage.

Acceptance

hard mailbox bounds use Sento's existing queue semantics;
existing FIFO and actor serialization behavior remain intact;
overload is typed/observable and never silent;
control remains responsive under data saturation;
Rabbit/HTTP/downstream admission is coupled to real bounded capacity;
no replacement queue backend, second scheduler, new StarLang syntax, or external controller;
implementation remains blocked until explicit operator authorization.

## Governance / ARDR state - Research authority: `lost-rob0t/starintel-auto-research/roam/research/ardr-issues/ARDR-ISSUE-190-sento-bounded-mailbox-admission.org` — `READY_FOR_DESIGN` - Design authority: `lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-043-sento-bounded-admission.org` — `DESIGN_READY_FOR_OPERATOR_REVIEW` - Dependencies: #34/#177 process budget; #35/#188/#189 Sento execution-lane accounting; #37/#182/#183 lifecycle/quiesce ownership - **Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL** ## Exact Sento finding Current StarIntel pin `mdbergmann/cl-gserver@6a510c5b58469e72e6363bd3a6059d80b9a5c320` already has the actor-local primitive we need: - `message-box-base` accepts `max-queue-size`; - `0`/`nil` selects an unbounded queue; - positive capacity selects `queue-bounded`; - bounded `pushq` immediately signals `queue-full-error` when full; - `queued-count` exposes current depth; - both pinned (`message-box/bt`) and dispatcher-backed (`message-box/dp`) mailboxes inherit this queue selection. Therefore **do not replace Sento's mailbox/queue backend for this P0**. Configure the existing bounded queue and add StarIntel admission/result semantics around it. ## Critical distinction Mailbox backlog and dispatcher concurrency are different resources: `mailbox capacity != dispatcher worker count` #35 bounds aggregate Sento execution lanes. This issue bounds queued work and composes that with HTTP, Rabbit, task and publication admission. ## Required behavior - Production data-plane actors use explicit positive mailbox capacities or a validated bounded default. - Full mailbox becomes a typed StarIntel overload result, not an uncaught raw `queue-full-error` and never silent success. - Default policy is reject/reply-busy. - Blocking admission is permitted only with an explicit absolute deadline and waits outside Sento's FIFO primitive. - `drop-old` is not a default policy; it discards already-accepted work and requires separate workload-specific proof. - Critical health/shutdown/supervision/lease-renewal traffic uses a separate bounded control path rather than queueing behind saturated data FIFO work. - Rabbit prefetch/in-flight derives from actual granted processing capacity plus a bounded per-worker factor; retire hard-coded 200 as independent authority. - HTTP admission occurs before expanding bulk requests into deeper actor/task work. - Task/publish/persistence handoff queues must be bounded; do not merely move the unbounded queue downstream. ## Typed overload result At minimum: boundary/component ID, reason, depth when observable, capacity, policy, optional justified retry-after, correlation/trace ID, timestamp. ## Proposed slices — ALL PENDING OPERATOR APPROVAL 1. Sento mailbox configuration + typed `queue-full-error` translation. 2. Explicit reject/reply-busy + deadline-bounded blocking admission API. 3. Separate control/data admission path proving control responsiveness under saturation. 4. Rabbit prefetch derivation from real granted processing capacity. 5. Downstream bounded task/publish queues + pressure diagnostics. ## RED-first targets 1. Capacity-2 actor: after two queued items, third submission must produce typed overload with depth=2/capacity=2 and zero handler invocation for the rejected item. 2. Same mailbox capacity remains 2 regardless of dispatcher worker count. 3. Blocking submission without deadline is rejected. 4. Saturated data mailbox does not block separate control health/stop fixture. 5. Rabbit fixture with granted worker count 2 no longer uses constant prefetch 200. 6. Synthetic actor -> task -> publish pipeline proves accepted outstanding work remains bounded at every stage. ## Acceptance - hard mailbox bounds use Sento's existing queue semantics; - existing FIFO and actor serialization behavior remain intact; - overload is typed/observable and never silent; - control remains responsive under data saturation; - Rabbit/HTTP/downstream admission is coupled to real bounded capacity; - no replacement queue backend, second scheduler, new StarLang syntax, or external controller; - implementation remains blocked until explicit operator authorization.