refactor(gateway/hosted_room_discussion): share _turn_coordinates across message and terminal payloads; tighten module docstrings

This commit is contained in:
Teknium
2026-09-02 19:16:56 -07:00
parent cf89a14df1
commit 995aa4abf5
3 changed files with 26 additions and 36 deletions
+16 -19
View File
@@ -1,14 +1,10 @@
"""Deterministic policy for same-gateway hosted-room Discussions.
Translates a frozen local member roster plus the complete typed room log into
one next driver task. Pure: no I/O, no workers, no transport or model
knowledge. Callers persist the task with :mod:`gateway.hosted_room_driver`
and append publication plans with :mod:`gateway.hosted_rooms`.
The driver payload is deliberately not widened: Discussion coordinates live
in deterministic ``TaskIdentity`` values and typed terminal events, so a
restart can reconstruct a task from durable state. Callers must reconcile
terminal driver rows into publication plans before asking for the next task.
Pure (no I/O, transport or model knowledge): a frozen local roster plus the complete
typed room log yields at most one next driver task. Discussion coordinates live in
deterministic ``TaskIdentity`` values and typed terminal events rather than a widened
driver payload, so a restart reconstructs tasks from durable state. Callers must
reconcile terminal driver rows into publication plans before asking for the next task.
"""
from __future__ import annotations
@@ -797,6 +793,15 @@ def reconstruct_task_plan(
return reconstructed
def _turn_coordinates(task: DiscussionTaskPlan) -> dict[str, Any]:
"""The coordinate fields every member message and terminal event carries."""
return {
"discussion_event_id": task.discussion_event_id, "member_id": task.member.member_id,
"member_index": task.member_index, "round_index": task.round_index, "task_id": task.identity.task_id,
"thread_id": task.identity.thread_id, "turn_id": task.identity.turn_id,
}
def _terminal_text(result: Any, *, field: str, fallback: str) -> str:
if isinstance(result, Mapping):
value = result.get(field)
@@ -829,11 +834,7 @@ def _settled_effects(
member_actor["display_name"] = task.member.display_name
effects.append(EventPlan(
event_id=message_event_id, kind="message.member", actor=member_actor,
payload={
"discussion_event_id": task.discussion_event_id, "member_id": task.member.member_id,
"member_index": task.member_index, "round_index": task.round_index, "task_id": task.identity.task_id,
"text": text, "thread_id": task.identity.thread_id, "turn_id": task.identity.turn_id,
},
payload={**_turn_coordinates(task), "text": text},
authority_gateway_id=room.gateway_id, authority_epoch=room.authority_epoch))
return {"message_event_id": None if passed else message_event_id, "passed": passed}, effects
@@ -901,11 +902,7 @@ def plan_publication(
terminal_event_id = (
f"ddeferred:{digest}:g{execution_generation}"
if effective_status == "deferred" else f"dterminal:{digest}")
common_payload = {
"discussion_event_id": task.discussion_event_id, "member_id": task.member.member_id,
"member_index": task.member_index, "round_index": task.round_index, "seen_through_seq": task.seen_through_seq,
"task_id": task.identity.task_id, "thread_id": task.identity.thread_id, "turn_id": task.identity.turn_id,
}
common_payload = {**_turn_coordinates(task), "seen_through_seq": task.seen_through_seq}
extra, effects = _TERMINAL_EFFECTS[effective_status](
result, task=task, room=room, message_event_id=f"dmessage:{digest}",
newer_same_thread=newer_same_thread, execution_generation=execution_generation)
+6 -10
View File
@@ -1,15 +1,11 @@
"""Replica store and takeover primitives for hosted Group Chat rooms.
The authority gateway owns a room's ordered log in ``gateway/hosted_rooms.py``;
this module gives every OTHER participant gateway a durable local copy plus the
fenced primitives to continue the room when the authority host dies:
``ingest_page()`` (idempotent, gap- and epoch-regression-safe replay),
``promote_replica()`` (resume locally at ``epoch + 1`` with a lineage-proving
``authority.claimed`` event) and ``demote_room()`` (a returning stale authority
records ``authority.lost`` when shown proof of a newer epoch).
Storage primitives only: none decide *when* takeover is safe. The caller must
establish that the previous owner can no longer commit before promoting.
Every non-authority participant gateway keeps a durable local copy of the room log
(``ingest_page()``: idempotent, gap- and epoch-regression-safe) plus fenced primitives to
continue the room when the authority host dies: ``promote_replica()`` resumes locally at
``epoch + 1`` with a lineage-proving ``authority.claimed`` event; ``demote_room()`` records
``authority.lost`` when a returning stale authority is shown a newer epoch. Storage
primitives only: the caller decides *when* takeover is safe.
"""
from __future__ import annotations
+4 -7
View File
@@ -1,12 +1,9 @@
"""Durable state for gateway-hosted Bot Mode rooms.
This module owns only hosted-room identity and its append-only event log. It
does not deliver events, lease relay work, or run agent turns; those belong to
the relay and the hosted-room driver, so the room log composes with a durable
relay without creating a second transport queue.
The caller supplies the database path so tests and alternate gateway layouts
can isolate state. Production handlers use the gateway's root ``state.db``.
Owns only hosted-room identity and its append-only event log; delivery, relay leasing
and agent turns belong to the relay and the hosted-room driver, so the log composes with
a durable relay without a second transport queue. Callers supply the database path
(production handlers use the gateway's root ``state.db``).
"""
from __future__ import annotations