feat: add websocket replay cursors

[Justinabox]

Summary

• Add bounded in-memory replay cursors for sanitized WebSocket envelopes.
• Support GET /ws?since=<cursor> with monotonic id fields, replay gap notices for too-old cursors, and invalid cursor rejection before WebSocket upgrade.
• Keep replay storage on the public serialize_event() privacy boundary, add cleanup for app-level event recorder subscriptions, and document the hello cursor/replay window.

Tests

• git diff --check
• PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/test_websocket.py -q
• PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/test_packaging_metadata.py tests/test_http_api_validation.py -q
• PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/ -q

Risks / notes

• Replay is process-local and bounded; it is not durable across restarts by design.
• Event filters are not on current main, so this PR preserves unfiltered behavior and can be extended to filter replay once Add WebSocket event filters for focused realtime subscribers #205 lands.

Closes #213

[Justinabox]

Release-manager review note for PR #214:

Classification: needs-fix before this can be considered for landing.

Current blocker after #212 landed:

• Merge-testing feat: add websocket replay cursors #214 over current origin/main (dc4d31e55b11b9ad42c15090c0da854aeaea30e9, which includes WebSocket events= filters from feat: filter websocket realtime events #212) produced content conflicts in:
  • README.md
  • server.py
  • tests/test_packaging_metadata.py
  • tests/test_websocket.py

Required fix:

1. Rebase/update the branch onto current main after feat: filter websocket realtime events #212.
2. Preserve the shipped WebSocket filter contract (selected_events, unsupported-filter rejection before upgrade/subscription, and docs/tests).
3. Make replay/cursor behavior filter-compatible: replay must only deliver sanitized envelopes whose public event names match the selected events= filter, and any replay gap/hello metadata must remain PII-safe.
4. Re-run at least:
   • git diff --check
   • PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/test_websocket.py tests/test_packaging_metadata.py -q
   • PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/ -q

No merge attempted for #214 in this pass.

[Justinabox]

Review-manager classification: needs-fix before review/landing.

This PR currently cannot be merge-tested over origin/main because it conflicts in:

• README.md
• server.py
• tests/test_packaging_metadata.py
• tests/test_websocket.py

I stopped at the conflict gate and did not run local behavior gates on a hand-resolved tree. Please rebase or merge current main, resolve the WebSocket docs/server/test conflicts against the recently landed realtime event filtering/docs changes, then rerun at least:

git diff --check
PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/test_websocket.py -q
PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/ -q

After that, the release lane can do a normal privacy/replay-cursor review. Until the conflicts are resolved, this remains needs-fix rather than a merge candidate.

[Justinabox]

Release review: needs-fix.

This draft is currently DIRTY against main, so it is not mergeable as-is. Please rebase or repackage it on current main, resolve conflicts without broadening scope, rerun git diff --check plus the full required Python 3.11 test suite, push the refreshed head, and request a new release review. No behavior was approved or merged in this pass.

[Justinabox]

Release-captain classification: needs-fix. This PR is now DIRTY against the current default branch after later safe merges. Please rebase/repackage it from current origin/main, resolve only the genuine overlap, then rerun git diff --check and the required no-hardware full pytest gate on the new head. Do not attempt to merge the stale head directly.

[Justinabox]

Release lane update: needs-human.

This change affects a sensitive security/privacy, production-deployment, modem/SIM, audio/hardware, or public realtime product boundary. It will not be autonomously merged under this lane. Please obtain an explicit Korgo decision on the intended policy/scope and, where applicable, rebase on current main with current gate evidence before requesting a new release review.

[Justinabox]

Release review: needs-fix.

This PR is now DIRTY against the default branch after recent safe merges. Do not merge the stale head directly. Refresh/rebase it in an isolated worktree, resolve the concrete overlap against current main, run git diff --check plus the required full pytest gate on the refreshed head, then return it for review.

[Justinabox]

Release review: needs-fix. GitHub currently reports this branch DIRTY against current main, so it cannot be safely evaluated or landed as-is. Rebase/repackage it from current main, resolve only the intended scope, inspect the resulting diff for overlap with work already shipped, and run git diff --check plus PYTHONPATH=. uv run --no-project --with pytest --with pytest-asyncio --with pytest-aiohttp --with pyserial-asyncio --with aiosqlite pytest tests/ -q. Request a fresh review on the new head; do not force a merge of the stale head.

[Justinabox]

Release review classification: needs-fix. GitHub now reports this branch DIRTY against the advanced default branch, so it is not mergeable. Please create an isolated rebase/repackage branch from current origin/main, resolve and review the overlap, run git diff --check plus the required full test suite on the rebased head, push it, and request a fresh release review. Do not attempt to merge this stale head directly.

[Justinabox]

Release-lane classification: needs-human.

Replay/cursor semantics affect authenticated realtime data retention, reconnect privacy, and externally visible API behavior. This old head needs an explicit product/security decision before any rebase or release review. No merge action taken in this lane.

[Justinabox]

Release-lane classification: needs human decision.

This introduces or documents a material product/operational behavior. It requires Korgo's decision on public semantics, retention/operations expectations, and rollout scope before an autonomous merge; local test success alone is not authorization to land it.

[Justinabox]

Release classification: needs-human.

This is a material product/API/data-lifecycle feature rather than a narrow corrective maintenance patch. It needs Korgo’s decision on product scope, compatibility, and operational/privacy semantics before autonomous landing. Keep it draft; after a decision, rebase/repackage over current main and run the prescribed gates.

[Justinabox]

Release review: needs-human. This PR is DIRTY and changes externally visible WebSocket replay/cursor/gap semantics. Approve the public contract before resolving/rebasing.