refactor(events): downshift server.stream.events schemas to aragora.events (P4a Batch 1d)

[scarmani]

Summary

P4a Batch 1d (Tier 1-2). Completes the downshift of the importable stream event schema surface (StreamEvent, StreamEventType, AudienceMessage) to the aragora.events layer, so foundation/infrastructure modules can reach the event dataclasses without importing aragora.server.

The schemas already live in aragora.events.types; this PR:

• Turns aragora/server/stream/events.py into a DeprecationWarning shim that re-exports the schemas from aragora.events.types (back-compat preserved; the warning message carries the old dotted path aragora.server.stream.events).

• Repoints the foundation/infrastructure-layer importers off the old path:

  • aragora/billing/cost_tracker.py (BUDGET_ALERT emit path)
  • aragora/events/dispatcher.py (TYPE_CHECKING import)

  so they no longer contribute the stream.events link to the events -> server / billing -> server layer edges.

Server-side stream runtime stays in place; only the importable schema surface moves. Domain/app callers (debate/, explainability/, ranking/) and the server-internal stream modules stay on the shim by-design - their DeprecationWarning is the intended two-sided signal (VAL-CROSS-004); full caller migration is post-mission shim-retire.

Refs: P4a layering foundation, epic #8257.

Validation (worktree off origin/main 3d2af8d)

• Two-sided shim (VAL-CROSS-004): importing aragora.server.stream.events emits a DeprecationWarning whose message contains aragora.server.stream.events; the shim re-exports all three symbols and imports only aragora.events (allowed-imports check PASS). Robust isolated check (worktree-resolved, __file__ asserted, token-filtered): TWO_SIDED_OK: True.
• Changed-file typecheck gate (required CI flags): mypy --ignore-missing-imports --follow-imports=skip --show-error-codes over the 3 touched files -> Success: no issues found in 3 source files.
• make lint: All checks passed. ruff format --check aragora/ tests/ scripts/: 10603 files already formatted.
• Targeted pytest: tests/billing/test_cost_tracker.py tests/server/stream/test_emitter.py tests/events/test_async_dispatcher.py tests/events/test_batch_dispatcher.py tests/events/test_security_dispatcher.py -> 218 passed (shim DeprecationWarning observed firing via emitter.py:19).
• make test-smoke (VAL-P4A-013): Core/Server/Memory imports OK, Smoke tests passed (exit 0).
• Smoke tier: PYTEST_BIN="python3 -m pytest" bash scripts/test_tiers.sh smoke -> 138 passed (exit 0).

Risks / notes

• Low. Pure import-source relocation + additive DeprecationWarning; symbol identities/values unchanged.
• The events -> server and billing -> server import-contract baseline edges are intentionally NOT shrunk: both packages retain other aragora.server.* importers (events: server.handlers.webhooks, server.middleware.tracing [Batch 1b deferred], server.stream.{state_manager,emitter}; billing: server.middleware.auth), so the edges stay alive even though the stream.events contribution is removed. Recorded as residual drift for the P4a seal/sweep.
• docs/METRICS.md / aragora/module_tiers.yaml NOT regenerated (path-frozen at P4a by chore(deps): update audit-vulnerable Python locks #8460/fix(ci): clear base security and smoke blockers #8461/feat(tier4): settle_tier4_pr.py — one-command --settle-apply + receipt-backed preapproval gate #8382 per the path-freeze carve-out); the resulting generated-file drift is recorded for the orchestrator-coordinated phase merge-train regen.

[github-actions]

Aragora Code Review

Advisory-only review. No issues found.

[scarmani]

Claude independent model review

Reviewer: claude (anthropic) — independent adversarial model review via the Aragora Claude reviewer, grounded on the exact PR head.
Head: 2b7b0f7 (2b7b0f7), committed 2026-06-30T21:51:13Z.
PR: #8732.
Model family: claude

Verdict: PASS

Reviewed the full change against the codebase. The refactor is backward-compatible and correct:

• cost_tracker.py / dispatcher.py now import StreamEvent/StreamEventType from aragora.events.types, where both symbols genuinely live — and the billing change correctly removes a billing → server layering import.

• events.py shim re-exports all three symbols (StreamEvent, StreamEventType, AudienceMessage) with a complete __all__; no symbol dropped. No circular-import risk (aragora.events.types imports only stdlib).

• No filterwarnings = error / -W error / simplefilter("error") anywhere in pyproject.toml, conftests, or test markers (the only filterwarnings uses are ignore:: filters), so the new module-level DeprecationWarning will not break collection or the suite.

• [P3] aragora/server/stream/events.py:20 — the new import-time warnings.warn(..., DeprecationWarning) is triggered by Aragora's own internal modules that still import from this deprecated path (e.g. aragora/server/stream/emitter.py:19, the lazy __getattr__ map in aragora/server/stream/__init__.py:24-26, plus debate_factory.py, broadcaster.py, voice_stream.py, arena_hooks.py, debate/intervention.py, explainability/builder.py, ranking/elo_matchmaking.py). The library thus emits its own deprecation warning during normal server startup. Since this is the "downshift" PR, prefer migrating the internal importers to aragora.events (or scoping the warning) so only external/legacy callers see it; harmless functionally (DeprecationWarnings are ignored by default), but self-inflicted and noisy.

dogfood: yes