Remove legacy interaction formats

Author: Chinmay Kabi

docs/README.md

@@ -29,7 +29,7 @@ should be verified in their own repositories.
 ## Current compatibility
 
 - package version: `0.8.0`;
-- session JSON schema: `9`;
+- session JSON schema: `10`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;
 - minimum Flutter SDK: `3.35.0`.

docs/design/capture-and-fingerprint.md

@@ -63,7 +63,7 @@ current controller and keeps future calls to `wrapApp` inert. Runtime
 requiring a host rebuild. `deactivate()` tears capture down through the same
 gate. Pause/hidden flush pending delivery; detach ends the session once.
 
-Identity fields (session schema **v10**; compatibility readers accept v6–v10):
+Identity fields (session schema **v10** only):
 
 - `activationRequestId` — host request correlation
 - `captureSessionId` — SDK-emitted session (`session.id`)
@@ -76,8 +76,7 @@ emits exact build and fingerprint-schema provenance only.
 ## Session and event model
 
 The controller owns one bounded, in-memory `TugboatSession`. Serialized session
-JSON is schema version `10`. Compatibility readers accept schema versions
-`6` through `10`. Schema v9 stopped writing `controlValue`,
+JSON is schema version `10` only. Schema v9 stopped writing `controlValue`,
 `controlValueTransition`, or `semanticAnnotation` in event `data`; those fields
 are optional historic data in older sessions only. Schema v10 removes
 serialized state identity and adds the `interaction` frame trigger.
@@ -99,8 +98,6 @@ The event stream currently includes:
 - lifecycle: `session_start`, `session_end`;
 - canonical gestures: `interaction` (`gesture`: `tap`, `swipe`, `scroll`,
   `cancelled`) with nested `payload` facts;
-- deprecated legacy gesture peers (`dualWrite` / `legacyOnly` only): `tap`,
-  `tap_settled`, `swipe`, `tap_outside_tree`;
 - navigation: `route_change`;
 - exploration control: `scene_inventory`, `action_window_set`,
   `action_window_cleared`;
@@ -119,11 +116,10 @@ route dictionary.
 
 `wrapApp` starts a session only after its repaint boundary has a non-zero
 viewport. The session begins with `session_start` and an initial capture
-request. Pointer-down records `tap` plus a compatible pre-interaction frame,
-then pointer-up either records a swipe or creates one `tap_settled` outcome.
-The settled event refers to the initial tap through `relatedEventId` and is
-intended to attach an after-frame only when that frame's provenance matches the
-observed route epoch. A capture that is unavailable, cancelled, superseded, or
+request. Pointer-down freezes a compatible pre-interaction frame. Pointer-up
+publishes one canonical `interaction` after gesture classification. Its
+after-frame attaches only when the frame provenance matches the observed route
+epoch. A capture that is unavailable, cancelled, superseded, or
 timed out is represented by bounded capture/attachment diagnostics instead of
 borrowing the latest frame from another screen.
 
@@ -338,8 +334,9 @@ The package test suite covers deterministic fingerprints, list-length and
 scroll stability, dynamic-label exclusion, static list discriminators, tag
 transparency, route separation, modal/visibility filtering, generated widget
 names, actionable `InkWell` paths, dormant activation without rebuild,
-screenshot mask defaults, route payloads, scroll/swipe attribution, schema-v7
-JSON with v6 read compatibility, semantic modes, sink factories/mailboxes,
+screenshot mask defaults, route payloads, scroll/swipe attribution, schema-v10
+JSON round trips and rejection of unsupported schema versions, semantic modes,
+sink factories/mailboxes,
 outbox restart recovery, health diagnostics, lifecycle ordering, retry bounds,
 and stale session/frame protection.
 

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,11 @@
+## Unreleased
+
+### Breaking changes
+
+- The SDK now publishes only schema-v2 canonical `interaction` gesture events.
+  Removed legacy gesture projections, publication modes, session aliases, and
+  compatibility constructors.
+
 ## 0.8.0
 
 ### Changed

packages/tugboat/README.md

@@ -5,9 +5,9 @@ checkpoints around meaningful interactions, compact structural anchors, route
 transitions, scrolling evidence, and optional viewport semantic maps. Capture
 can be sent to the local exploration WebSocket, the HTTP collector, or both.
 
-The current package version is `0.8.0`. Session JSON writers emit schema
-version `10`; compatibility readers should accept versions `6` through
-`10`. Structural fingerprints use fingerprint schema version `6`.
+The current package version is `0.8.0`. Session JSON writers and readers use
+schema version `10` only. Structural fingerprints use fingerprint schema
+version `6`.
 
 ## 0.8.0 raw-event compatibility
 
@@ -182,7 +182,7 @@ Navigator/repaint-boundary contract.
 Each visible route change creates a route epoch and waits for the transition
 plus the configured settle delay before taking the destination capture. A newer
 visible route supersedes an older pending capture. Consequently, a route event
-and a related `tap_settled` event are intended to reference a frame compatible
+and a related canonical `interaction` are intended to reference a frame compatible
 with that route epoch, or report bounded degraded/capture diagnostics rather
 than attach an origin-route frame merely because it was the latest frame.
 
@@ -191,30 +191,12 @@ Production acceptance for #13/#14 remains open: rapid or nested modal chains
 and programmatic/automatic navigation can still be absent or degraded. Treat
 those cases as an SDK capture gap, not as coherent replay evidence.
 
-### Deferred taps and interaction claims
+### Interaction claims
 
-`tap` is sampled at pointer-down but emitted only after gesture classification
-(or when a claimed `route_change` must publish a cause). Consumers must read:
-
-| Field | Meaning |
-| --- | --- |
-| `data.replayRole` | `interaction` (real user tap) or `causal_only` (cause id for a route; not a replayable action) |
-| `data.gestureFinal` | `tap`, `swipe`, `cancelled`, `superseded`, `session_end`, or `unresolved` |
-| `data.sampledAtMs` | Pointer-down sample time when the event was published later |
-| `data.captureCoordinate` | Boundary-local / normalized / raster transform for the before-frame |
-| `route_change.data.navigationOrigin` | `interaction` or `automatic_or_unknown` |
-| `route_change.data.causeEventId` | Claimed tap id when origin is `interaction` |
-| `route_change.data.interactionAttribution` | Always `same_turn` when claimed |
-| `swipe` (legacy dual-write) `.data.invalidatesRelatedTap` | Boolean `true` when a related causal tap should be ignored for playback |
-| `tap_gesture_resolved` | Promotes `relatedEventId` from `causal_only` → interaction (`promotesRelatedTap`) |
-
-Released pointer-up claims attribute a route only through the pointer-up turn
-(sync `onTap` → `Navigator.push`). Timer/auth redirects after that turn stay
-`automatic_or_unknown`. Backgrounding and `session_end` drop pending claims
-without minting orphan `causal_only` taps for cancelled routes.
-
-**Downstream contract:** Context Graph and PMKit CLI must not treat
-`replayRole: causal_only` taps as real actions or step openers.
+Pointer-down freezes interaction origin data. Pointer-up classifies the gesture
+and publishes one canonical `interaction`. A claimed `route_change` uses that
+interaction ID as `causeEventId`. Released pointer-up claims apply only through
+the pointer-up turn. Timer or auth redirects stay `automatic_or_unknown`.
 
 ## Capture profiles and runtime state
 
@@ -250,9 +232,8 @@ Identity contract:
 - `explorationRunId` — exploration control-plane ID from config
 - `traitsId` — collector-issued traits dictionary id after `setTraits` / session responses
 
-`TugboatReplay.activeSessionId` remains as a deprecated alias for
-`activationRequestId`. Inspect `TugboatReplay.health` for sink/outbox/screenshot
-budget pressure without reading protected content.
+Inspect `TugboatReplay.health` for sink, outbox, and screenshot-budget pressure
+without reading protected content.
 
 ### User traits and user id
 
@@ -300,7 +281,6 @@ Call `TugboatReplay.clearDurableOutbox()` on logout/consent revocation.
 | `profile` | `dormant` | capture cost and exploration-only behavior |
 | `settleDelay` | 1 second | delay before post-interaction and post-route capture |
 | `interactionClaimWindow` | 1,250 ms | released-tap window for delayed route/modal attribution; `Duration.zero` keeps microtask-only same-turn claims |
-| `interactionPublishMode` | `canonicalOnly` | how finalized gestures are published; new recordings emit one canonical `interaction`. `legacyOnly` and `dualWrite` are deprecated compatibility modes |
 | `maxFrames` | 500 | in-memory frame bound |
 | `maxEvents` | 5000 | in-memory event bound |
 | `scrollCaptureInterval` | 2 seconds | interval for scroll checkpoint capture |
@@ -321,46 +301,6 @@ Call `TugboatReplay.clearDurableOutbox()` on logout/consent revocation.
 | `outbox` | disabled | durable HTTP outbox configuration |
 | `screenshotBudget` | 60ms / 5s window | degraded-capture skip window / budget |
 
-### Legacy gesture projection deprecation
-
-New recordings default to `TugboatInteractionPublishMode.canonicalOnly`. One
-completed physical gesture produces one semantic `interaction` event containing
-its immutable origin, finalized gesture, result, attribution, and evidence IDs.
-The SDK no longer emits separate `tap`, `tap_settled`, or `swipe` rows unless an
-integration explicitly opts into a legacy mode.
-
-`dualWrite` and `legacyOnly` remain available temporarily so older collectors,
-Context Graph revisions, dashboards, and replay fixtures can be migrated without
-making historical recordings unreadable:
-
-- `canonicalOnly` — supported default for all new recordings;
-- `dualWrite` — deprecated migration override that adds legacy peers on
-  `stream: legacy_projection` with `enrichmentCandidate: false`;
-- `legacyOnly` — deprecated emergency compatibility override for consumers that
-  cannot yet read canonical `interaction` records.
-
-Do not enable either legacy mode in a new application integration. Consumers
-must use `interaction` as the user action and treat route/frame records as
-linked evidence. Historical `tap` and `tap_settled` rows may still be read and
-correlated through `interactionId` / `relatedEventId`, but must not be counted as
-additional user actions.
-
-The code marker `TODO(tugboat-legacy-projection-removal)` tracks final removal.
-Remove the legacy enum values and emission branches in a future breaking SDK
-release only after all of the following are true:
-
-1. Supported Collector and Context Graph versions consume canonical
-   `interaction` records and ignore legacy projections by default.
-2. Dashboard, insight, rage-tap, and replay queries no longer depend on
-   `tap_settled` or legacy `swipe` rows.
-3. Production telemetry confirms that current SDK versions are recording
-   canonical interactions successfully across representative tap, navigation,
-   scroll, cancellation, and lifecycle cases.
-4. Retained dual-write fixtures remain available to test historical replay
-   compatibility after the emitters are deleted.
-5. Release notes announce the removal and the SDK schema/breaking version is
-   advanced deliberately.
-
 ### Resolver and exploration events
 
 When exploration is active, the controller may emit:
@@ -371,10 +311,6 @@ When exploration is active, the controller may emit:
 | `viewport_semantic_map` | Bounded semantic node map (mode-dependent) |
 | `scroll_semantic_snapshot` | Semantic snapshot tied to scroll checkpoints |
 | `action_window_set` / `action_window_cleared` | CLI exploration action-window fencing |
-| `tap_outside_tree` | Pointer resolved no target; carries the same `replayRole` / `gestureFinal` as the paired tap when deferred |
-| `tap_gesture_resolved` | Promotes a prior `causal_only` tap (`promotesRelatedTap: true`, `relatedEventId`) after the gesture finalizes as a real tap |
-
-Consumers that filter `replayRole: causal_only` must honor `tap_gesture_resolved` (or the patched in-memory tap) before suppressing genuine navigations.
 
 ## Privacy and payload boundary
 
@@ -427,9 +363,6 @@ Emitted inferred event types currently include:
 - canonical: `interaction` (`stream: semantic`) — one finalized gesture
   (`tap`, `swipe`, `scroll`, or `cancelled`) with gesture-specific facts under
   `payload` (omitted for `cancelled`);
-- deprecated legacy gesture peers (emitted only when an integration explicitly
-  selects `dualWrite` or `legacyOnly`): `tap`, `tap_settled`, `swipe`,
-  `tap_outside_tree`, `tap_gesture_resolved`;
 - lifecycle: `session_start`, `session_identify`, `session_end`;
 - navigation evidence (`stream: evidence`): `route_change`;
 - diagnostics: `capture_diagnostic` (`stream: diagnostic`);
@@ -442,7 +375,7 @@ Default enrichment and insight selection should use inferred events:
 `stream: semantic` `interaction` records (`enrichmentCandidate: true` on
 collector payloads).
 Rage-tap style insights must count finalized `gesture=tap` interactions;
-exclude scrolls, swipes, cancellations, evidence, legacy projections, and
+exclude scrolls, swipes, cancellations, evidence, and
 diagnostics.
 
 Frames can be triggered by initial startup, interactions, routes, lifecycle,
@@ -457,25 +390,17 @@ local-WebSocket suppression, paint-generation reuse, dHash reuse, or
 content-hash reuse. A fresh route capture can satisfy only the interaction that
 causally claimed it.
 
-Pointer coordinates in event data (`x`, `y`, and swipe `startX`/`startY`) are
-Flutter global logical-pixel coordinates from the pointer event. The SDK
-converts a copy into its capture boundary's local space only for hit-testing and
-normalizing target/viewport-semantic bounds; stored event coordinates are not
-capture-boundary-normalized for replay playback. Do not interpret them as
-physical pixels or as coordinates relative to an individual widget. Fractional
-overlay drift is therefore still possible.
+Interaction payload coordinates use normalized capture-boundary space. Do not
+interpret them as physical pixels or as coordinates relative to a widget.
 
 For a tap, origin context (target, `beforeFrame`,
 `captureCoordinate`, route/navigator identity) is frozen at pointer-down into
 an `InteractionTransaction`. After pointer-up, settlement waits for either the
 first eligible visible successor inside `interactionClaimWindow` (default
 1,250 ms) or the deadline. The canonical `interaction` event retains that
 frozen origin and attaches destination/result fields when a successor claims.
-When deprecated dual-write compatibility is explicitly enabled, legacy `tap` +
-`tap_settled` records link via `relatedEventId` / `interactionId`. They are not
-additional semantic actions. A missing attachment is explicit in
-`frameAttachment`/settle diagnostics rather than a fallback to an unrelated
-frame.
+A missing attachment remains unavailable. The SDK does not attach an unrelated
+frame as a fallback.
 
 During local WebSocket exploration, connecting without an HTTP collector
 suppresses only non-interaction Flutter screenshot capture for UI-thread

packages/tugboat/lib/src/collector_config.dart

@@ -8,15 +8,6 @@ class TugboatCollectorAppInfo {
     required this.appId,
   });
 
-  @Deprecated('Use TugboatCollectorAppInfo(appId: ...) instead.')
-  const TugboatCollectorAppInfo.legacyPackageName({
-    required this.name,
-    required this.version,
-    required this.buildNumber,
-    required this.installationId,
-    required String packageName,
-  }) : appId = packageName;
-
   final String name;
   final String version;
   final String buildNumber;