feat: Add root-isolate predicate and pin secondary-isolate plugin behaviour (#5302)

Groundwork for the #5302 category guardrails. No behaviour change: the only
production change is a new `@internal` getter, and nothing consumes it yet.

- `amplifyIsInRootIsolate` in amplify_flutter: true for an app's main isolate
  and for a headless `FlutterEngine` entry point, false only inside
  `Isolate.spawn`. Built on `ServicesBinding.rootIsolateToken`, so it cannot
  false-positive on the root isolate.
- Pins today's behaviour: a native-backed plugin added from a secondary isolate
  is accepted *silently*, while a pure-Dart plugin correctly still works, and
  the root isolate keeps tolerating an already-configured native SDK.

The guard itself is deliberately not included. `AmplifyCategory.addPlugin`
(amplify_core/lib/src/category/amplify_categories.dart:91-101) already catches
`AmplifyAlreadyConfiguredException` and registers the plugin anyway, so the
exception never reaches `amplify_flutter`. A guard in `hybrid_impl.dart` was
written, proven dead by test, and reverted rather than shipped.

Author: cadivus

packages/amplify/amplify_flutter/lib/src/amplify_isolate.dart

@@ -22,6 +22,28 @@ RootIsolateToken? get amplifyRootIsolateToken {
   return RootIsolateToken.instance;
 }
 
+/// {@template amplify_flutter.amplify_is_in_root_isolate}
+/// Whether the current isolate is a root isolate, meaning it owns a Flutter
+/// engine and therefore drives the process-wide native Amplify SDKs.
+///
+/// True on an app's main isolate, and also on the root isolate of a headless
+/// `FlutterEngine` — for example the entry point that records a push
+/// notification while the app is killed. Both of those own an engine, so both
+/// may configure native Amplify.
+///
+/// False only in an isolate started with `Isolate.spawn`, which has no engine
+/// of its own. Such an isolate can still use categories that run entirely in
+/// Dart, but the native SDKs already belong to the root isolate.
+///
+/// Always true on the web, which has no isolates.
+/// {@endtemplate}
+@internal
+bool get amplifyIsInRootIsolate {
+  // `RootIsolateToken.instance` throws on the web rather than returning null.
+  if (kIsWeb) return true;
+  return ServicesBinding.rootIsolateToken != null;
+}
+
 /// {@template amplify_flutter.amplify_isolate_is_initialized}
 /// Whether the current isolate can reach Amplify's platform channels.
 ///

packages/amplify/amplify_flutter/test/isolate_guardrails_test.dart

@@ -0,0 +1,171 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Groundwork and ground truth for the #5302 category guardrails.
+//
+// It establishes `amplifyIsInRootIsolate` — the predicate a guard has to be
+// built on — and pins what Amplify does *today* when a native-backed plugin is
+// added from a secondary isolate. The pinned behaviour is the bug: the plugin is
+// accepted silently. When the guard lands, the `silently accepts` test below is
+// expected to invert, which is the point of pinning it now.
+
+@TestOn('vm')
+library;
+
+import 'dart:async';
+import 'dart:isolate';
+
+import 'package:amplify_core/amplify_core.dart';
+import 'package:amplify_flutter/src/amplify_isolate.dart';
+import 'package:amplify_flutter/src/hybrid_impl.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+/// Stands in for a native-backed plugin whose native side is already configured
+/// by another isolate.
+///
+/// amplify-android reports exactly this: an `AlreadyConfiguredException` mapped
+/// to `AmplifyAlreadyConfiguredException`, verified on device in #7266.
+class NativeAlreadyConfiguredPlugin extends AnalyticsPluginInterface {
+  // Deliberately does not call super: it models native registration failing
+  // outright rather than completing.
+  @override
+  // ignore: must_call_super
+  Future<void> addPlugin({
+    required AmplifyAuthProviderRepository authProviderRepo,
+  }) async {
+    throw const AmplifyAlreadyConfiguredException(
+      'Amplify has already been configured.',
+    );
+  }
+}
+
+/// A plugin that runs entirely in Dart, which #7266 proved must keep working in
+/// a secondary isolate.
+class PureDartPlugin extends AnalyticsPluginInterface {
+  @override
+  Future<void> configure({
+    AmplifyOutputs? config,
+    required AmplifyAuthProviderRepository authProviderRepo,
+  }) async {}
+}
+
+/// What [addPluginInIsolate] observed, sent back over a [SendPort].
+typedef IsolateReport = Map<String, Object?>;
+
+/// Builds a fresh [AmplifyHybridImpl] in the isolate this runs in and adds
+/// either the native-backed or the pure-Dart plugin to it.
+Future<void> addPluginInIsolate((SendPort, bool) message) async {
+  final (sendPort, useNativePlugin) = message;
+  final report = <String, Object?>{'inRootIsolate': amplifyIsInRootIsolate};
+  final amplify = AmplifyHybridImpl();
+  try {
+    await amplify.addPlugin(
+      useNativePlugin ? NativeAlreadyConfiguredPlugin() : PureDartPlugin(),
+    );
+    report['errorType'] = null;
+  } on Object catch (e) {
+    report['errorType'] = e.runtimeType.toString();
+    report['error'] = '$e';
+  }
+  report['pluginCount'] = amplify.Analytics.plugins.length;
+  sendPort.send(report);
+}
+
+/// Spawns [addPluginInIsolate] and waits for its [IsolateReport].
+Future<IsolateReport> runInIsolate({required bool useNativePlugin}) async {
+  final receivePort = ReceivePort();
+  final errorPort = ReceivePort();
+  final result = Completer<IsolateReport>();
+
+  receivePort.listen((message) {
+    if (!result.isCompleted) {
+      result.complete((message as Map).cast<String, Object?>());
+    }
+  });
+  errorPort.listen((message) {
+    if (!result.isCompleted) {
+      result.completeError(StateError('Isolate errored: $message'));
+    }
+  });
+
+  final isolate = await Isolate.spawn(
+    addPluginInIsolate,
+    (receivePort.sendPort, useNativePlugin),
+    onError: errorPort.sendPort,
+    errorsAreFatal: true,
+    debugName: 'guardrail-probe',
+  );
+  try {
+    return await result.future.timeout(const Duration(seconds: 30));
+  } finally {
+    isolate.kill(priority: Isolate.immediate);
+    receivePort.close();
+    errorPort.close();
+  }
+}
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  group('amplifyIsInRootIsolate', () {
+    test('is true on a root isolate', () {
+      // `flutter_tester` gives a real engine root isolate, which is the same
+      // state a headless `FlutterEngine` entry point runs in. This is what keeps
+      // `amplifyBackgroundProcessing` out of any guard built on this predicate:
+      // that function calls `WidgetsFlutterBinding.ensureInitialized()` and a
+      // plain `MethodChannel`, so it can only ever run with an engine attached.
+      expect(amplifyIsInRootIsolate, isTrue);
+    });
+
+    test('is false in a spawned isolate', () async {
+      final report = await runInIsolate(useNativePlugin: false);
+
+      expect(report['inRootIsolate'], isFalse);
+    });
+  });
+
+  group('adding plugins from a secondary isolate', () {
+    test('works for a plugin that runs entirely in Dart', () async {
+      final report = await runInIsolate(useNativePlugin: false);
+
+      expect(report['errorType'], isNull);
+      expect(report['pluginCount'], 1);
+    });
+
+    // CURRENT BEHAVIOUR, and the bug #5302 needs fixed. `AmplifyCategory
+    // .addPlugin` (packages/amplify_core/lib/src/category/amplify_categories
+    // .dart:91-101) catches `AmplifyAlreadyConfiguredException` and adds the
+    // plugin anyway, so the caller sees success while native never registered
+    // this isolate's plugin. Nothing in `amplify_flutter` observes the exception,
+    // because the category swallowed it first.
+    test('silently accepts a native-backed plugin', () async {
+      final report = await runInIsolate(useNativePlugin: true);
+
+      expect(report['inRootIsolate'], isFalse);
+      expect(
+        report['errorType'],
+        isNull,
+        reason: 'If this now throws, the guard has landed — invert this test',
+      );
+      expect(
+        report['pluginCount'],
+        1,
+        reason: 'Plugin is registered on the Dart side despite native failing',
+      );
+    });
+  });
+
+  group('adding plugins on the root isolate', () {
+    test('still tolerates an already-configured native SDK', () async {
+      // The app-restart / hot-restart path: native outlives the Dart isolate, so
+      // re-registering must stay a no-op. Any guard must not change this.
+      final amplify = AmplifyHybridImpl();
+
+      await expectLater(
+        amplify.addPlugin(NativeAlreadyConfiguredPlugin()),
+        completes,
+      );
+      expect(amplify.Analytics.plugins, hasLength(1));
+    });
+  });
+}