feat(replay): consolidate interaction evidence

[Chinmay-KB]

Summary

Each completed user gesture now has one canonical interaction record with its immutable starting context, outcome, attribution, and supporting evidence. Legacy tap, settle, and swipe records remain available as compatibility projections while downstream consumers move to the canonical stream.

The interaction transaction also prevents scrolls and cancelled gestures from becoming phantom taps, preserves pointer-down context through delayed UI changes, and keeps diagnostics and routing evidence out of semantic enrichment by default.

Validation

Manually exercised the production-lean Blend build using the local SDK in session session-1785324031005003. The captured run included paywalls, dialogs, canvas/editor interactions, scrolling, and navigation; recorded taps had before-frames, settled interactions had before/after evidence, and navigations had destination frames.

Release

Tugboat SDK version: 0.4.15. The changelog documents the canonical interaction stream, delayed reconciliation, compatibility projection, and gesture-finalization fixes.

[Copilot]

Pull request overview

This PR introduces a canonical, consolidated interaction model for Tugboat replay: each finalized user gesture is represented by a single interaction event (semantic stream) with frozen origin context, outcome/attribution, and linked evidence; legacy tap/tap_settled/swipe remain available as compatibility projections on a separate stream.

Changes:

• Add InteractionTransaction + registry to freeze pointer-down origin and reconcile delayed successors via interactionClaimWindow.
• Introduce event streams (semantic/evidence/diagnostic/legacy_projection) and update collector mapping/enrichment-candidate selection accordingly.
• Bump session schema to v8, SDK version to 0.4.15, and expand tests/docs to cover canonical interactions, claim windows, and gesture finalization.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/tugboat/lib/src/controller.dart	Replaces pending-tap/claim logic with interaction transactions; emits canonical interaction and stream-tagged evidence/diagnostics.
packages/tugboat/lib/src/interaction_transaction.dart	New transaction + registry types for immutable origin, delayed reconciliation, and terminalization.
packages/tugboat/lib/src/models.dart	Adds schema v8, event streams, publish modes, enrichment-candidate logic, and event copy APIs.
packages/tugboat/lib/src/replay_config.dart	Adds interactionClaimWindow and interactionPublishMode configuration.
packages/tugboat/lib/src/collector_mapper.dart	Adds stream/enrichmentCandidate fields to collector payloads.
packages/tugboat/lib/src/coordinate_space.dart	Improves missing-frame coordinate output (keeps boundary-local/normalized info; distinguishes outside-boundary).
packages/tugboat/lib/tugboat.dart	Exposes default reconciliation window constant.
packages/tugboat/lib/src/sdk_version.dart	Bumps SDK version constant to 0.4.15.
packages/tugboat/pubspec.yaml	Bumps package version to 0.4.15.
packages/tugboat/CHANGELOG.md	Documents 0.4.15 interaction consolidation, streams, attribution window, and fixes.
packages/tugboat/README.md	Updates docs for deferred taps/claims and event streams (but needs version/schema sync).
docs/README.md	Updates compatibility summary (but needs version/schema sync).
docs/plans/2026-07-28-001-sdk-interaction-consolidation-plan.md	New implementation plan/contract documenting the consolidation approach and requirements.
docs/integration/production-replay-acceptance.md	Updates acceptance guidance to reference 0.4.15 interaction consolidation gates.
docs/integration/production-replay-acceptance-0.4.15.md	New acceptance checklist for the 0.4.15 canonical interaction model.
docs/integration/production-replay-acceptance-0.4.13.md	New historical acceptance doc for 0.4.13 comparison/gates.
docs/integration/production-replay-run-2026-07-27-sdk-0.4.12.md	New production run report used as baseline evidence.
packages/tugboat/test/helpers/replay_coherence_harness.dart	Adds interactionClaimWindow to test harness config defaults.
packages/tugboat/test/helpers/json_roundtrip.dart	Updates JSON round-trip helpers for stream + schema v8 acceptance.
packages/tugboat/test/tugboat_replay_test.dart	Updates tests for schema v8 and claim-window config.
packages/tugboat/test/integration/release_compatibility_matrix_test.dart	Updates schema expectations to v8 and adds claim-window config.
packages/tugboat/test/collector_mapper_test.dart	Verifies stream + enrichmentCandidate mapping behavior.
packages/tugboat/test/coordinate_space_test.dart	Expands tests for missing-frame/outside-boundary coordinate behavior.
packages/tugboat/test/scroll_playground_live_test.dart	Adds claim-window config to stabilize behavior.
packages/tugboat/test/scroll_attribution_test.dart	Updates attribution assertions for swipe-only behavior (no phantom taps).
packages/tugboat/test/scene_inventory_test.dart	Updates pointer tests to record pointer-up and claim-window config.
packages/tugboat/test/viewport_semantic_map_test.dart	Updates pointer tests to record pointer-up and claim-window config.
packages/tugboat/test/replay/tap_coordinate_transform_test.dart	Updates pointer tests to record pointer-up and claim-window config.
packages/tugboat/test/replay/replay_programmatic_navigation_matrix_test.dart	Adjusts ordering to reflect deferred tap emission and correct causal attribution.
packages/tugboat/test/replay/replay_overlay_nested_navigation_matrix_test.dart	Adds claim-window config.
packages/tugboat/test/replay/replay_navigation_interaction_matrix_test.dart	Adds claim-window config.
packages/tugboat/test/replay/replay_navigation_race_matrix_test.dart	Adds new test coverage around automatic route superseding + visual successor behavior.
packages/tugboat/test/replay/navigation_origin_contract_test.dart	Expands contract tests for same-turn attribution, lifecycle/session-end fencing, and claim expiry behavior.
packages/tugboat/test/replay/modal_capture_visual_test.dart	Adds claim-window config.
packages/tugboat/test/replay/replay_coherence_characterization_test.dart	Updates characterization expectations to match new swipe/tap attribution behavior.
packages/tugboat/test/replay/deferred_tap_emission_test.dart	New tests for pointer-down buffering, swipe/cancel behavior, and claimed-then-swiped cause resolution.
packages/tugboat/test/replay/interaction_transaction_test.dart	New tests validating origin freeze, delayed reconciliation, canonical publish, and diagnostic isolation.

Comments suppressed due to low confidence (2)

docs/README.md:35

• docs/README.md ‘Current compatibility’ section is out of sync with this PR’s version/schema bump (0.4.15 / schema 8). Update to match the released SDK contract.

- package version: `0.4.13`;
- session JSON schema: `7`;
- fingerprint schema: `6`;
- minimum Dart SDK: `3.9.2`;
- minimum Flutter SDK: `3.35.0`.

packages/tugboat/lib/src/controller.dart:2608

• _clearReleasedInteractions() hard-codes InteractionRejectionReason.sessionEnd, but it’s also used for non-session-end shutdown paths (e.g. lifecycle pause). This makes attribution diagnostics misleading; consider parameterizing the reason (defaulting to sessionEnd) and pass lifecycle when clearing due to backgrounding.

    for (final tx in _interactions.takeAllReleased()) {
      _finalizeAbandonedTransaction(
        tx,
        reason: InteractionRejectionReason.sessionEnd,
      );

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.