refactor(relay): purge platform-specific scope terminology from the relay adapter (D-Q2.5c)

[hashbender]

What & why

The gateway half of D-Q2.5c (connector half: NousResearch/gateway-gateway#92). The D-Q2.5 wire migration renamed the relay scope discriminator guild_id → scope_id behind a dual-read/dual-write overlap. Prod + staging are now on scope_id, so this removes the legacy alias — and, per the ask, purges all platform-specific (Discord "guild") scope terminology within the relay adapter.

Hard scope boundary

Every change is inside gateway/relay/, its tests, or the relay contract doc. session.py and all native platform adapters are untouched.

SessionSource.guild_id is an agent-wide field (native Discord/Matrix/Teams/qqbot adapters populate it; the discord-tools prompt reads it) — it is not relay-only, so it stays. The relay wire path never calls session.py.to_dict(); it builds/reads frames directly in gateway/relay/, so the relay wire is fully migratable in isolation.

Changes (relay adapter only)

• ws_transport._event_from_wire — read scope_id only (drop the ?? guild_id fallback).
• adapter._with_scope — emit scope_id only on outbound metadata (drop the guild_id dual-write); docstring "GUILD reply" → "SCOPED reply".
• adapter._capture_scope — read source.scope_id only; rename local guild var → scope; genericize the _scope_by_chat / _dm_user_by_chat field comments (guild_id (Discord) → scope_id (server/workspace scope)).
• __init__.relay_route_keys docstring — guild_ids → scope_ids.
• One real Discord guild_id kept: the raw inbound interaction payload read (payload.get("guild_id")), which is Discord's own wire field, mapped straight into the generic scope_id slot.

Contract doc

Reframed the guild_id row as a legacy alias the connector no longer reads — session.py's agent-wide to_dict() still emits it (mirrored to scope_id) for non-relay session persistence, so it stays documented + wire-present but ignored. This is accurate and keeps the to_dict()-vs-doc conformance test green.

Gate (all green)

• 156 relay tests pass, ruff clean.
• Cross-repo E2E — all 14 drivers pass BOTH deploy orders:
  • connector fix(bedrock): guard against null url in image_url parts and lifecycle status (#55686) #92 (scope_id-only) × agent origin/main (still dual-reads) ✅
  • connector fix(bedrock): guard against null url in image_url parts and lifecycle status (#55686) #92 (scope_id-only) × this branch (scope_id-only) ✅
• So the two PRs are deploy-order-independent — either can land first.

Paired PR

• NousResearch/gateway-gateway#92 — the connector half.

🤖 Solo relay lane (D-Q2.5c). Relay paths touch no manifest → not Teknium-gated.

---

Mirror-of: NousResearch#56016
NousResearch#56016

[tenki-reviewer]

Review Complete
No issues found!

Risk: 🟢 Low (15/100) — no findings · 145 LOC across 10 files

---

PR replaces guild_id with scope_id throughout the gateway relay layer, updating the transport protocol, adapter, tests, and connector contract docs. No regressions or security issues introduced.

Files Reviewed (10 files)

docs/relay-connector-contract.md
gateway/relay/__init__.py
gateway/relay/adapter.py
gateway/relay/ws_transport.py
tests/gateway/relay/test_relay_adapter.py
tests/gateway/relay/test_relay_multiplatform.py
tests/gateway/relay/test_relay_passthrough.py
tests/gateway/relay/test_relay_roundtrip.py
tests/gateway/relay/test_relay_roundtrip_telegram.py
tests/gateway/relay/test_ws_transport.py