feat(protocol_dto): add canonical serialization for protocol DTOs

[leostar0412]

Summary

Adds canonical serialization for tracker protocol DTOs (TrackerResult, IncrementalState, ActivityRecord) so collectors and observability tooling share one JSON shape instead of ad-hoc dict assembly.

• New core/protocol_dto.py with shared frozen base dataclasses: TrackerResultDataclass, IncrementalStateDataclass, ActivityRecordDataclass
• Each base provides asdict(), to_json() (deterministic, ISO-8601 datetimes), from_dict(), and log-friendly truncated __repr__
• GenericTrackerResult, GenericIncrementalState, and new GenericActivityRecord inherit the bases; all 11 tracker protocol_impl.py modules refactored to subclass them (repr=False on subclasses so truncation is preserved)
• format_occurred_at_z() promoted to public in core/activity_types.py for shared datetime serialization
• BaseCollectorCommand logs result_repr and result_json in structured extra when the run result is a TrackerResultDataclass
• GitHub/Discord to_legacy_dict() kept unchanged for Tier-C workspace bridge JSON

Apps touched

• core
• github_activity_tracker
• discord_activity_tracker
• cppa_slack_tracker
• boost_mailing_list_tracker
• clang_github_tracker
• cppa_pinecone_sync
• boost_library_usage_dashboard
• wg21_paper_tracker
• boost_library_tracker
• boost_library_docs_tracker
• cppa_youtube_script_tracker

Test plan

• uv run pytest core/tests/test_protocol_serialization.py core/tests/test_collector_protocol_conformance.py core/tests/test_protocols.py core/tests/test_collectors_base.py core/tests/test_activity_types.py
• uv run pytest */tests/test_protocol_impl.py (app protocol_impl smoke tests)
• uv run pyright
• lint-imports (no new cross-app imports; worth running in CI)
• App command smoke-tested (collector/command changed): not required — serialization-only change; no collector behavior change beyond structured logging fields

Docs / coupling

• cross-app-dependencies.md updated (if FKs or cross-app imports changed) — N/A
• python scripts/generate_service_docs.py run (if services.py or core/protocols.py changed) — N/A (core/protocols.py unchanged)
• App README or docs/ updated (if behavior or ops changed) — docs/Core_public_API.md, CHANGELOG.md

---

Closes #277

Summary by CodeRabbit

Release Notes

• New Features

  • Protocol Data Transfer Objects now support canonical serialization via asdict(), to_json(), and from_dict() methods with bounded, log-friendly __repr__ output.
  • Added GenericActivityRecord as a default implementation for activity tracking.

• Changed

  • Collector logging now includes structured result_repr and result_json fields for improved observability.

• Documentation

  • Updated public API documentation to reflect protocol DTO serialization capabilities and logging behavior.

• Tests

  • Added comprehensive protocol serialization round-trip and determinism tests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de3c193e-3265-4bb7-b706-76af71e4568a

📥 Commits

Reviewing files that changed from the base of the PR and between e0e4dac and 4dcf205.

📒 Files selected for processing (21)

• CHANGELOG.md
• boost_library_docs_tracker/protocol_impl.py
• boost_library_tracker/protocol_impl.py
• boost_library_usage_dashboard/protocol_impl.py
• boost_mailing_list_tracker/protocol_impl.py
• clang_github_tracker/protocol_impl.py
• core/activity_record.py
• core/activity_types.py
• core/collectors/__init__.py
• core/collectors/command_base.py
• core/incremental_state.py
• core/protocol_dto.py
• core/tests/test_protocol_serialization.py
• core/tracker_result.py
• cppa_pinecone_sync/protocol_impl.py
• cppa_slack_tracker/protocol_impl.py
• cppa_youtube_script_tracker/protocol_impl.py
• discord_activity_tracker/protocol_impl.py
• docs/Core_public_API.md
• github_activity_tracker/protocol_impl.py
• wg21_paper_tracker/protocol_impl.py

---

📝 Walkthrough

Walkthrough

This PR implements comprehensive protocol DTO serialization for tracker result, incremental state, and activity record types. A new core/protocol_dto.py module defines shared frozen dataclass bases with canonical asdict(), to_json(), and from_dict() methods plus truncated __repr__. Eleven tracker apps' DTO implementations are refactored to inherit from these bases, removing duplicate field declarations and immutability logic. Logging is enhanced to include result_repr and result_json for TrackerResultDataclass results. Tests validate round-trip serialization and determinism.

Changes

Protocol DTO Serialization & Tracker App Consolidation

Layer / File(s)	Summary
Protocol DTO base classes and serialization API core/protocol_dto.py	Three frozen dataclass bases—TrackerResultDataclass, IncrementalStateDataclass, ActivityRecordDataclass—each with deterministic asdict(), JSON-safe to_json(), generic from_dict() deserialization, type coercion, and log-friendly __repr__ truncation via helpers (_json_safe, _repr_mapping, _truncate_summary).
Default generic implementations and core utilities core/tracker_result.py, core/incremental_state.py, core/activity_record.py, core/activity_types.py, core/collectors/__init__.py	GenericTrackerResult, GenericIncrementalState, and GenericActivityRecord are thin frozen specializations inheriting from protocol DTO bases. format_occurred_at_z() helper is promoted to public for ISO-8601 timestamp normalization. GenericActivityRecord exported from collectors module.
Collector logging integration core/collectors/command_base.py	_log_collector_result() detects TrackerResultDataclass subclasses at runtime and enriches structured log extra with result_repr and result_json fields for observability.
Tracker DTO refactorings to shared bases boost_library_docs_tracker/protocol_impl.py, boost_library_tracker/protocol_impl.py, boost_library_usage_dashboard/protocol_impl.py, boost_mailing_list_tracker/protocol_impl.py, clang_github_tracker/protocol_impl.py, cppa_pinecone_sync/protocol_impl.py, cppa_slack_tracker/protocol_impl.py, cppa_youtube_script_tracker/protocol_impl.py, discord_activity_tracker/protocol_impl.py, github_activity_tracker/protocol_impl.py, wg21_paper_tracker/protocol_impl.py	Tracker-specific DTO implementations (TrackerResult, IncrementalState, ActivityRecord) across 11 apps converted from standalone frozen dataclasses with explicit fields to inherit from shared protocol bases. Local immutability-wrapping __post_init__ hooks and duplicate field declarations removed. Dataclass repr=False delegates to base-class bounded representation.
Serialization tests, documentation, and changelog core/tests/test_protocol_serialization.py, docs/Core_public_API.md, CHANGELOG.md	Comprehensive round-trip validation (from_dict(asdict()) equivalence), deterministic JSON checks, and repr truncation tests. Public API documentation updated to describe protocol DTO structure and logging behavior. Changelog records serialization enhancements and logging changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• cppalliance/boost-data-collector#279: This PR builds directly on #279's TrackerResult protocol migration by refactoring the same tracker DTOs to inherit from shared serialization bases and extending logging infrastructure.
• cppalliance/boost-data-collector#260: Both PRs update GitHub and Discord *ActivityRecord protocol DTO implementations with overlapping code-level changes to activity record field types and serialization helpers.

Suggested reviewers

• jonathanMLDev
• snowfox1003
• wpak-ai

Poem

🐰 Protocol DTO consolidation, a tidy refrain,
Frozen dataclasses dance through each tracker domain,
Canonical asdict() and JSON so clear,
Truncated __repr__ for logs—no more fear,
Serialization unified, where duplication once lay!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.31% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding canonical serialization for protocol DTOs with the new core/protocol_dto.py module.
Description check	✅ Passed	The description is comprehensive, covering Summary, Apps touched, Test plan with checkmarks, and Docs/coupling sections per template. All major sections are populated with substantive detail.
Linked Issues check	✅ Passed	The PR fully addresses all acceptance criteria from #277: repr with truncation, asdict(), to_json() with ISO-8601 and deterministic ordering, round-trip from_dict(), and comprehensive test coverage across all 12 affected apps.
Out of Scope Changes check	✅ Passed	All changes are in-scope: new core/protocol_dto.py, refactoring 11 tracker protocol_impl.py files to inherit base classes, promoting format_occurred_at_z(), and adding structured logging fields in BaseCollectorCommand are all directly tied to the #277 objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}