fix: comprehensive hardening across engine lifecycle, storage, replay security, and surfaces

docs/development-guide/03-core-internals.md

@@ -67,6 +67,13 @@ Future<void> startMasterSearch(String query);
 // Prevents race: clear() while records being written
 ```
 
+Fencing lifecycle: `_pendingGenerations` + `Expando` propagation via
+`copyWith`, `clearSync`/`clear` generation bump, `_sentGenerations` drop in
+`_handleEntryReady` (null means fenced and must drop). Policy is
+`clear-wins`: writes racing clear are dropped. Double bump is intentional —
+second fence drops entries recorded during `await writer.clear()` so
+`engine.entries` is empty after `await clear()`.
+
 ---
 
 ## 3.2 `CapturePipeline` & `WriterIsolate` — Off-Main-Thread Processing

packages/interceptly/CHANGELOG.md

@@ -1,3 +1,12 @@
+## Unreleased
+
+### Fixed
+- Preserve capture generation across `HttpRequestContext.copyWith` so amended scopes stay fenced after `clear()`.
+- Generation-fenced `clear`/`clearRest`/`clearRealtime` with per-scope futures; `clear-wins` linearization documented.
+- Writer restart aliasing via `_StopAck` handshake with `preserveExisting` resume and rotation-count propagation.
+- `getRequestDetail` reads beyond UI preview via full decode and propagates `hasDataLoss` to `isTruncated`; `totalChars` now measures full bodies (previously measured UI-preview truncation).
+- Rotation sync for detail loader and search; active realtime notifier retention; bound restart queue.
+
 ## 2.3.0
 
 ### Added

packages/interceptly/lib/src/adapter/http_request_context.dart

@@ -1,5 +1,7 @@
 import 'dart:typed_data';
 
+import '../engine/capture_generation.dart';
+
 /// Immutable context tracking an ongoing HTTP request capture lifecycle.
 class HttpRequestContext {
   /// Creates an immutable [HttpRequestContext].
@@ -45,7 +47,7 @@ class HttpRequestContext {
     Uint8List? requestBodyBytes,
     String? requestContentType,
   }) {
-    return HttpRequestContext(
+    final copy = HttpRequestContext(
       id: id,
       method: method ?? this.method,
       uri: uri ?? this.uri,
@@ -54,5 +56,7 @@ class HttpRequestContext {
       requestBodyBytes: requestBodyBytes ?? this.requestBodyBytes,
       requestContentType: requestContentType ?? this.requestContentType,
     );
+    attachCaptureGeneration(copy, readCaptureGeneration(this));
+    return copy;
   }
 }

packages/interceptly/lib/src/adapter/http_traffic_collector.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/foundation.dart';
 
 import '../capture/capture_guard.dart';
+import '../engine/capture_generation.dart';
 import '../model/network_simulation.dart';
 import '../model/raw_capture.dart';
 import '../engine/interceptly_engine.dart';
@@ -116,7 +117,11 @@ class DefaultHttpTrafficCollector implements HttpTrafficCollector {
     if (uri == null) return true;
     final predicate = engine.settings.shouldCapture;
     if (predicate == null) return true;
-    return predicate(uri.toString());
+    try {
+      return predicate(uri.toString());
+    } catch (_) {
+      return true;
+    }
   }
 
   @override
@@ -167,6 +172,7 @@ class DefaultHttpTrafficCollector implements HttpTrafficCollector {
         requestBodyBytes: bodyBytes,
         requestContentType: resolvedContentType,
       );
+      attachCaptureGeneration(context, engine.httpGeneration);
 
       guardCapture(() {
         engine.recordPending(
@@ -270,6 +276,7 @@ class DefaultHttpTrafficCollector implements HttpTrafficCollector {
         requestTruncatedAtStorage: isRequestTruncated,
         responseTruncatedAtStorage: isResponseTruncated,
       );
+      attachCaptureGeneration(capture, readCaptureGeneration(context));
 
       engine.record(capture);
     });
@@ -336,6 +343,7 @@ class DefaultHttpTrafficCollector implements HttpTrafficCollector {
         requestTruncatedAtStorage: isRequestTruncated,
         responseTruncatedAtStorage: isResponseTruncated,
       );
+      attachCaptureGeneration(capture, readCaptureGeneration(context));
 
       engine.record(capture);
     });

packages/interceptly/lib/src/adapter/realtime_session_scope.dart

@@ -91,6 +91,9 @@ class RealtimeSessionScope {
     });
   }
 
+  /// Normalizes [data] once and forwards the computed preview and size
+  /// so [RealtimeTrafficCollector.recordFrame] hits its fast path without
+  /// renormalizing the payload.
   void _record(dynamic data, FrameDirection direction, {String? eventName}) {
     if (data == null) return;
     final normalized = FrameNormalizer.normalize(

packages/interceptly/lib/src/adapter/realtime_traffic_collector.dart

@@ -108,7 +108,11 @@ class DefaultRealtimeTrafficCollector implements RealtimeTrafficCollector {
     if (uri == null) return true;
     final predicate = engine.settings.shouldCapture;
     if (predicate == null) return true;
-    return predicate(uri.toString());
+    try {
+      return predicate(uri.toString());
+    } catch (_) {
+      return true;
+    }
   }
 
   @override

packages/interceptly/lib/src/capture/frame_normalizer.dart

@@ -43,6 +43,7 @@ class FrameNormalizer {
   ///
   /// - Computes [originalSizeBytes] with 0 heap byte allocations for UTF-8 text via [utf8ByteLength].
   /// - Avoids cloning [Uint8List] / [ByteData] buffers (uses [Uint8List.sublistView] when truncating).
+  /// - Caps generic [List<int>] windows with take before copying to avoid full allocation.
   /// - Generates a safe Unicode [shortPreview] (<= 128 chars).
   /// - Flags [shouldOffload] when [originalSizeBytes] >= [offloadThreshold] and [offloadThreshold] > 0.
   /// - Pre-encodes [preEncodedBytes] once when [shouldOffload] is true, eliminating downstream re-encoding.
@@ -85,9 +86,18 @@ class FrameNormalizer {
     } else if (raw is List<int> && explicitType != FrameType.text) {
       type = explicitType ?? FrameType.binary;
       originalSize = raw.length;
-      final bytes = raw is Uint8List ? raw : Uint8List.fromList(raw);
+      final Uint8List bytes;
+      if (raw is Uint8List) {
+        bytes = raw;
+      } else if (maxBodyBytes > 0 && originalSize > maxBodyBytes) {
+        bytes = Uint8List.fromList(raw.take(maxBodyBytes).toList());
+      } else {
+        bytes = Uint8List.fromList(raw);
+      }
       shouldOffload = offloadThreshold > 0 && originalSize >= offloadThreshold;
-      final capped = (maxBodyBytes > 0 && originalSize > maxBodyBytes)
+      final capped = (maxBodyBytes > 0 &&
+              originalSize > maxBodyBytes &&
+              bytes.length > maxBodyBytes)
           ? bytes.sublist(0, maxBodyBytes)
           : bytes;
       payload = capped;

packages/interceptly/lib/src/capture/stream_capture.dart

@@ -98,9 +98,11 @@ Stream<List<int>> teeStreamCapture(
       Future<void> deliveryChain = Future<void>.value();
 
       void handleChunk(List<int> chunk) {
-        if (settled || controller.isClosed) return;
+        if (controller.isClosed) return;
         controller.add(chunk);
-        buffer.add(chunk);
+        if (!settled) {
+          buffer.add(chunk);
+        }
       }
 
       sub = source.listen(
@@ -133,16 +135,19 @@ Stream<List<int>> teeStreamCapture(
           deliveryChain = deliveryChain.then((_) {
             if (!isCanceled) {
               finishDone();
-              controller.close();
+              if (!controller.isClosed) {
+                controller.close();
+              }
             }
           }).catchError((_) {});
         },
         onError: (Object e, StackTrace st) {
           deliveryChain = deliveryChain.then((_) {
             if (!isCanceled) {
               finishError(e, st);
-              controller.addError(e, st);
-              controller.close();
+              if (!controller.isClosed) {
+                controller.addError(e, st);
+              }
             }
           }).catchError((_) {});
         },

packages/interceptly/lib/src/core/interceptly_controller.dart

@@ -43,6 +43,15 @@ class Interceptly {
     Stream<void>? customTrigger,
     InterceptlySettings? settings,
   }) {
+    /// Release guard evaluated before mutating the singleton, so a release
+    /// call without opt-in leaves existing engine settings untouched.
+    if (kReleaseMode) {
+      final allowInRelease =
+          settings?.allowInRelease ?? engine.settings.allowInRelease;
+      if (!allowInRelease) {
+        return Future<void>.value();
+      }
+    }
     if (settings != null) engine.configure(settings);
 
     return _init(

packages/interceptly/lib/src/engine/body_decode_service.dart

@@ -116,12 +116,14 @@ class BodyDecodeService {
   /// Returns a preview of [bytes] truncated to [previewLen] bytes,
   /// or `null` when [bytes] is null or empty.
   ///
-  /// If [maxBody] <= 0 (unlimited) or [bytes.length] <= [maxBody],
-  /// the full buffer is returned unchanged.
+  /// The retained window is capped by the smallest of [previewLen],
+  /// [maxBody] (when positive), and the buffer length, so a large preview
+  /// budget can never exceed the storage cap.
   static Uint8List? truncate(Uint8List? bytes, int maxBody, int previewLen) {
     if (bytes == null || bytes.isEmpty) return null;
     if (maxBody <= 0 || bytes.length <= maxBody) return bytes;
-    final end = previewLen < bytes.length ? previewLen : bytes.length;
+    var end = previewLen < bytes.length ? previewLen : bytes.length;
+    if (end > maxBody) end = maxBody;
     return bytes.sublist(0, end);
   }