feat(sessionize): add deterministic event-aware boundaries to segmentation

[YuvarajGML]

Summary

Add deterministic, opt-in event-aware segmentation so callers can supply externally authoritative events such as git.merge, pr.approved, or deploy.success and have the sessionization pipeline split existing segments at captured boundaries.

The change is a small post-processing layer on top of the existing segmentation algorithm and preserves backward compatibility when no events are provided.

What changed

• Added Event dataclass in src/activity_frames/events.py:
  • event_type: str
  • timestamp: float
  • source: str
  • priority: int
• Added optional event arguments to the core segmentation/frame-building APIs:
  • events
  • forced_event_types
  • force_priority
• Added deterministic event-boundary helpers:
  • _apply_event_boundaries(...)
  • _split_segment_by_event(...)
  • _event_matches(...)
• Preserved Python 3.9 compatibility by avoiding Python 3.10 union syntax.

With events=(), existing behavior is unchanged.

Example

from activity_frames.events import Event
from activity_frames.sessionize import segments

event = Event(
    event_type="git.merge",
    timestamp=1660451520.0,
    source="git",
    priority=10,
)

segs = segments(
    observations,
    events=[event],
    forced_event_types={"git.merge"},
)

The event is mapped to the captured boundary immediately after the last observation at or before the event timestamp. No synthetic observations are created.

Tests

• Full test suite: 116 passed
• Command: python -m pytest -q

Coverage includes:

• forced event splits
• event timestamp matching an observation
• non-forced events being ignored
• priority-based matching and ordering
• out-of-range events
• empty-event backward compatibility
• timestamps falling between captured observations

Validation

• Wheel and sdist build successfully
• Python 3.9, 3.11, and 3.13 compatibility considered
• Imports and typing checked
• No new circular imports introduced

Review focus

• Confirm the deterministic ordering of events by (timestamp ASC, priority DESC).
• Confirm the current behavior for splits that would otherwise create an empty side.
• Review whether Event should be exported publicly and whether additional API documentation is needed.

Files of interest

• src/activity_frames/events.py
• src/activity_frames/sessionize.py
• tests/test_event_boundaries.py