1010
1111from roomkit .channels .base import Channel
1212from roomkit .core .circuit_breaker import CircuitBreaker
13+ from roomkit .core .lanes import DeliveryPlan
1314from roomkit .core .rate_limiter import TokenBucketRateLimiter
1415from roomkit .core .retry import retry_with_backoff
1516from roomkit .core .transcoder import DefaultContentTranscoder
@@ -146,28 +147,67 @@ def get_channel(self, channel_id: str) -> Channel | None:
146147 """Look up a channel by ID."""
147148 return self ._channels .get (channel_id )
148149
149- async def broadcast (
150+ def plan (
150151 self ,
151152 event : RoomEvent ,
152153 source_binding : ChannelBinding ,
153154 context : RoomContext ,
154155 * ,
155156 exclude_delivery : set [str ] | None = None ,
156- ) -> BroadcastResult :
157- """Broadcast an event to all eligible channels in the room.
157+ ) -> DeliveryPlan :
158+ """Resolve an event's delivery set (RFC §10.1 step 12).
159+
160+ Pure — no I/O, no awaits — so it runs under the room lock: the target
161+ set is consistent with the committed timeline. Execution
162+ (:meth:`execute_plan`) does not require the lock.
163+
164+ A source that cannot write (RFC §7.5 — guards reentry events and
165+ direct broadcast callers; inbound events from non-writable sources
166+ are blocked before broadcast) yields an empty delivery set.
167+ """
168+ if not source_binding .can_write :
169+ logger .debug (
170+ "Source %s cannot write (access=%s, muted=%s) — not broadcasting" ,
171+ source_binding .channel_id ,
172+ source_binding .access ,
173+ source_binding .muted ,
174+ extra = {"room_id" : event .room_id , "channel_id" : source_binding .channel_id },
175+ )
176+ targets : list [ChannelBinding ] = []
177+ else :
178+ # Stamp visibility from source binding
179+ if event .visibility == Visibility .ALL and source_binding .visibility != Visibility .ALL :
180+ event = event .model_copy (update = {"visibility" : source_binding .visibility })
181+ # Target bindings include muted channels — they can still read.
182+ targets = self ._filter_targets (event , source_binding , context .bindings )
183+ return DeliveryPlan (
184+ event = event ,
185+ source_binding = source_binding ,
186+ context = context ,
187+ targets = targets ,
188+ exclude_delivery = exclude_delivery ,
189+ )
190+
191+ async def execute_plan (self , plan : DeliveryPlan ) -> BroadcastResult :
192+ """Execute a plan's delivery set (RFC §10.1 step 14).
158193
159194 RFC §3.8: For each target channel:
160195 - on_event(): all channels react (intelligence generates, observers analyze)
161196 - deliver(): only transport channels push to external recipients
162197
163- Args:
164- exclude_delivery: Channel IDs to skip delivery for (already
165- received content via streaming ).
198+ Runs without the room lock; per-room ordering is the caller's
199+ contract (the delivery lane, or an inline caller running to
200+ completion ).
166201 """
167202 from roomkit .telemetry .base import Attr , SpanKind
168203 from roomkit .telemetry .context import get_current_span , reset_span , set_current_span
169204 from roomkit .telemetry .noop import NoopTelemetryProvider
170205
206+ event = plan .event
207+ source_binding = plan .source_binding
208+ context = plan .context
209+ exclude_delivery = plan .exclude_delivery
210+
171211 telemetry = self ._telemetry or NoopTelemetryProvider ()
172212 session_id = (event .metadata or {}).get ("voice_session_id" )
173213 span_id = telemetry .start_span (
@@ -176,38 +216,20 @@ async def broadcast(
176216 parent_id = get_current_span (),
177217 room_id = event .room_id ,
178218 session_id = session_id ,
179- attributes = {Attr .CHANNEL_ID : source_binding .channel_id },
219+ attributes = {Attr .CHANNEL_ID : source_binding .channel_id if source_binding else "" },
180220 )
181221 # Propagate backend-specific context for robust parent linking
182222 broadcast_token = set_current_span (
183223 span_id , telemetry_ctx = telemetry .get_span_context (span_id )
184224 )
185225
186226 result = BroadcastResult ()
227+ targets = plan .targets
187228
188- # Check source can write (RFC §7.5). Inbound events from non-writable
189- # sources are already blocked before broadcast in the inbound pipeline;
190- # this guards reentry events and any direct broadcast callers.
191- if not source_binding .can_write :
192- logger .debug (
193- "Source %s cannot write (access=%s, muted=%s) — not broadcasting" ,
194- source_binding .channel_id ,
195- source_binding .access ,
196- source_binding .muted ,
197- extra = {"room_id" : event .room_id , "channel_id" : source_binding .channel_id },
198- )
199- reset_span (broadcast_token )
200- telemetry .end_span (span_id , attributes = {"target_count" : 0 })
201- return result
202-
203- # Stamp visibility from source binding
204- if event .visibility == Visibility .ALL and source_binding .visibility != Visibility .ALL :
205- event = event .model_copy (update = {"visibility" : source_binding .visibility })
206-
207- # Determine target bindings (includes muted channels — they can still read)
208- targets = self ._filter_targets (event , source_binding , context .bindings )
209-
210- if not targets :
229+ # An injected plan (bare on_event/deliver, no transcode, no reentry)
230+ # is executed by the framework host, never here; a plan with no
231+ # source binding has nothing to transcode from either way.
232+ if not targets or source_binding is None :
211233 reset_span (broadcast_token )
212234 telemetry .end_span (span_id , attributes = {"target_count" : 0 })
213235 return result
@@ -467,6 +489,29 @@ async def _process_target(binding: ChannelBinding) -> None:
467489
468490 return result
469491
492+ async def broadcast (
493+ self ,
494+ event : RoomEvent ,
495+ source_binding : ChannelBinding ,
496+ context : RoomContext ,
497+ * ,
498+ exclude_delivery : set [str ] | None = None ,
499+ ) -> BroadcastResult :
500+ """Plan and execute in one call — the inline path.
501+
502+ Running to completion where the caller stands trivially satisfies
503+ per-room order (RFC §10.2). The inbound pipeline instead calls
504+ :meth:`plan` under the room lock and hands execution to the room's
505+ delivery lane.
506+
507+ Args:
508+ exclude_delivery: Channel IDs to skip delivery for (already
509+ received content via streaming).
510+ """
511+ return await self .execute_plan (
512+ self .plan (event , source_binding , context , exclude_delivery = exclude_delivery )
513+ )
514+
470515 def _filter_targets (
471516 self ,
472517 event : RoomEvent ,
0 commit comments