Merge pull request #35 from blendto/codex/production-event-parameters

feat: allow production event parameter capture

Author: Chinmay-KB

docs/README.md

@@ -28,7 +28,7 @@ should be verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.6.0`;
+- package version: `0.7.0`;
 - session JSON schema: `9`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;

docs/integration/production-replay-acceptance.md

@@ -12,7 +12,7 @@ database receipt alone as proof that a replay is correct.
 
 ## Current acceptance status
 
-The current SDK release candidate is **0.5.0**, which writes session schema
+The current SDK release candidate is **0.7.0**, which writes session schema
 **v9**. It preserves structural interaction replay while no longer emitting
 `controlValue`, `controlValueTransition`, or `semanticAnnotation` in event
 data. Treat the absence of those fields as the expected privacy boundary, not
@@ -164,7 +164,7 @@ flows share a session, list the event IDs or timestamps that delimit each flow.
 
 Wait until the collector session has finalized and the replay is available in
 the production website. Filter to the recorded Blend build and SDK version
-under test (`0.5.0` for this release), then open every recorded session.
+under test (`0.7.0` for this release), then open every recorded session.
 
 For each interaction, inspect the actual replay UI and verify:
 

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.7.0
+
+### Added
+
+- **Explicit production parameter opt-in** —
+  `TugboatParameterPolicy.allowAllInProduction` retains JSON-safe external-event
+  parameter values in production capture profiles. `namesOnly` remains the
+  default. `allowAll` remains an exploration-only escape hatch and still
+  downgrades to names-only outside exploration. The existing JSON and size
+  bounds still apply. This policy can retain feedback, search terms, URLs, IDs,
+  and other user content. Hosts must confirm consent, privacy, access, and
+  retention rules before they use it.
+
 ## 0.6.0
 
 ### Changed

packages/tugboat/README.md

@@ -5,7 +5,7 @@ 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.6.0`. Session JSON writers emit schema
+The current package version is `0.7.0`. Session JSON writers emit schema
 version `9`; compatibility readers should accept versions `6` through
 `9`. Structural fingerprints use fingerprint schema version `6`.
 
@@ -23,7 +23,7 @@ The package requires Dart 3.9.2 or newer and Flutter 3.35.0 or newer.
 
 ```yaml
 dependencies:
-  tugboat_dio: ^0.6.0
+  tugboat_dio: ^0.7.0
 ```
 
 See `packages/tugboat_dio/README.md`.
@@ -58,12 +58,35 @@ failedCall.complete(
 ```
 
 Both emit on `stream: evidence` and never inherit exploration `actionId` or UI
-anchors. Parameter values are omitted unless an explicit policy allows them.
-`allowAll` is an exploration escape hatch; outside exploration profiles the SDK
-downgrades it to names-only at record time. Network routes must be absolute path
-templates. The SDK drops resolver output containing a scheme, query, fragment,
-percent-encoded data, a network-path prefix, backslash, or whitespace/control
-characters; host resolvers must still replace dynamic IDs with placeholders.
+anchors. `namesOnly` is the default parameter policy. It retains parameter keys
+but omits parameter values. `allowAll` is an exploration-only escape hatch;
+outside exploration profiles the SDK downgrades it to names-only at record time.
+
+### Production parameter values
+
+Use `allowAllInProduction` only when the host needs to retain all JSON-safe
+parameter values in a production capture profile:
+
+```dart
+final productionEvents = TugboatReplay.eventHook(
+  source: 'feedback',
+  parameterPolicy: TugboatParameterPolicy.allowAllInProduction,
+);
+productionEvents.record(
+  'FEEDBACK_SUBMITTED',
+  parameters: {'comment': 'The search result was not useful.'},
+);
+```
+
+This policy can retain feedback, search terms, URLs, IDs, and other user
+content. Hosts must confirm consent, privacy, access, and retention rules before
+they use it. The SDK still deep-copies JSON-safe values and applies its hard
+JSON and size bounds.
+
+Network routes must be absolute path templates. The SDK drops resolver output
+containing a scheme, query, fragment, percent-encoded data, a network-path
+prefix, backslash, or whitespace/control characters; host resolvers must still
+replace dynamic IDs with placeholders.
 HTTP response bodies are retained only when `statusCode >= 400`. JSON and text
 are deep-copied and bounded to 16 KiB; binary and unsupported values are
 omitted. Successful response bodies are never retained.
@@ -533,8 +556,9 @@ sink registration API has not been published.
   output.
 - Nested navigator and anonymous-route identity depends on structural fallback
   and needs app-specific validation.
-- The package captures no logs, network traffic, analytics events, or native
-  performance signals.
+- The package captures no logs or native performance signals. It supports
+  opt-in external events and network observations with the privacy boundaries
+  described above.
 
 See [Collector integration](../../docs/integration/collector.md) and
 [Capture and fingerprint status](../../docs/design/capture-and-fingerprint.md)

packages/tugboat/example/pubspec.yaml

@@ -32,7 +32,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  tugboat: ^0.6.0
+  tugboat: ^0.7.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

packages/tugboat/lib/src/external_event.dart

@@ -7,13 +7,17 @@ enum TugboatParameterCaptureMode {
   namesOnly,
   allowList,
   transform,
-  allowAll;
+  allowAll,
+  allowAllInProduction;
 
   String get wireName => switch (this) {
     TugboatParameterCaptureMode.namesOnly => 'names_only',
     TugboatParameterCaptureMode.allowList => 'allow_list',
     TugboatParameterCaptureMode.transform => 'transform',
-    TugboatParameterCaptureMode.allowAll => 'allow_all',
+    // Both retain-all modes share the wire label; production scope is carried
+    // by the mode itself, not a parallel flag.
+    TugboatParameterCaptureMode.allowAll ||
+    TugboatParameterCaptureMode.allowAllInProduction => 'allow_all',
   };
 }
 
@@ -27,7 +31,8 @@ class TugboatParameterDrop {
 ///
 /// Parameter keys may be captured by default. Values are captured only through
 /// an explicit allow-list, transform, or the deliberately named [allowAll]
-/// exploration escape hatch.
+/// exploration escape hatch. [allowAllInProduction] is a separate production
+/// opt-in.
 class TugboatParameterPolicy {
   const TugboatParameterPolicy._({
     required this.mode,
@@ -67,6 +72,18 @@ class TugboatParameterPolicy {
     mode: TugboatParameterCaptureMode.allowAll,
   );
 
+  /// Production opt-in that retains all JSON-safe values within hard limits.
+  ///
+  /// This can capture feedback, search terms, URLs, IDs, and other user
+  /// content. The host must confirm consent, privacy, access, and retention
+  /// rules before it uses this policy.
+  ///
+  /// Unlike [allowAll], this policy retains values in production capture
+  /// profiles. It still applies all parameter safety and size limits.
+  static const allowAllInProduction = TugboatParameterPolicy._(
+    mode: TugboatParameterCaptureMode.allowAllInProduction,
+  );
+
   /// Sentinel for transform callbacks.
   static const drop = TugboatParameterDrop._();
 
@@ -261,7 +278,8 @@ _ValueDecision _decideTopLevelValue(
       key,
       value,
     ),
-    TugboatParameterCaptureMode.allowAll => _KeepValue(value),
+    TugboatParameterCaptureMode.allowAll ||
+    TugboatParameterCaptureMode.allowAllInProduction => _KeepValue(value),
   };
 }
 

packages/tugboat/lib/src/sdk_version.dart

@@ -1,3 +1,3 @@
 // Keep this in sync with packages/tugboat/pubspec.yaml. The SDK version test
 // reads pubspec.yaml directly so release bumps fail fast if this drifts.
-const tugboatSdkVersion = '0.6.0';
+const tugboatSdkVersion = '0.7.0';

packages/tugboat/pubspec.yaml

@@ -1,7 +1,7 @@
 name: tugboat
 description: >-
   Screenshot-based session replay with compact interaction anchors for Tugboat.
-version: 0.6.0
+version: 0.7.0
 repository: https://github.com/blendto/tugboat-flutter
 issue_tracker: https://github.com/blendto/tugboat-flutter/issues
 homepage: https://github.com/blendto/tugboat-flutter

packages/tugboat/test/external_event_and_network_test.dart

@@ -140,6 +140,82 @@ void main() {
     });
   });
 
+  testWidgets('production opt-in retains bounded JSON-safe parameter values', (
+    tester,
+  ) async {
+    await _pumpCapture(
+      tester,
+      config: _testConfig.copyWith(
+        profile: TugboatCaptureProfile.productionLean,
+      ),
+    );
+
+    TugboatReplay.eventHook(
+      parameterPolicy: TugboatParameterPolicy.allowAllInProduction,
+    ).record('SEARCH', parameters: {'query': 'private search', 'page': 2});
+
+    final event = TugboatReplay.controller!.session!.events.singleWhere(
+      (event) => event.type == 'external_event',
+    );
+    expect(event.data['parameterKeys'], ['query', 'page']);
+    expect(event.data['parameters'], {'query': 'private search', 'page': 2});
+    expect(event.data['capture'], {
+      'values': 'allow_all',
+      'truncated': false,
+      'droppedCount': 0,
+    });
+  });
+
+  testWidgets('exploration capture retains allow-all parameter values', (
+    tester,
+  ) async {
+    await _pumpCapture(tester);
+
+    TugboatReplay.eventHook(
+      parameterPolicy: TugboatParameterPolicy.allowAll,
+    ).record('SEARCH', parameters: {'query': 'private search'});
+
+    final event = TugboatReplay.controller!.session!.events.singleWhere(
+      (event) => event.type == 'external_event',
+    );
+    expect(event.data['parameterKeys'], ['query']);
+    expect(event.data['parameters'], {'query': 'private search'});
+    expect(event.data['capture'], {
+      'values': 'allow_all',
+      'truncated': false,
+      'droppedCount': 0,
+    });
+  });
+
+  test('effectiveFor only downgrades exploration allowAll', () {
+    expect(
+      TugboatParameterPolicy.allowAll.effectiveFor(
+        TugboatCaptureProfile.productionLean,
+      ),
+      same(TugboatParameterPolicy.namesOnly),
+    );
+    expect(
+      TugboatParameterPolicy.allowAllInProduction.effectiveFor(
+        TugboatCaptureProfile.productionLean,
+      ),
+      same(TugboatParameterPolicy.allowAllInProduction),
+    );
+    expect(
+      TugboatParameterPolicy.allowAllInProduction.mode,
+      TugboatParameterCaptureMode.allowAllInProduction,
+    );
+    expect(
+      TugboatParameterPolicy.allowAllInProduction.captureValues,
+      'allow_all',
+    );
+    expect(
+      TugboatParameterPolicy.allowAll.effectiveFor(
+        TugboatCaptureProfile.exploration,
+      ),
+      same(TugboatParameterPolicy.allowAll),
+    );
+  });
+
   testWidgets('external event ignores active action window', (tester) async {
     await _pumpCapture(tester);
     final controller = TugboatReplay.controller!;

packages/tugboat_dio/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.7.0
+
+### Changed
+
+- Compatibility release for `tugboat` 0.7.0. The Dio adapter has no runtime
+  behavior changes.
+
 ## 0.6.0
 
 ### Added