halkyon_app: instances, sign-in and sync plumbing for Halkyon's apps

What every Halkyon app's shell needs, taken from Halkyon Learn's and set
on halkyon_base's client: the instances a device keeps an account on,
the first start's tiles and where an instance keeps people's data, the
account switcher; signing in anonymously, with GitHub or an email code,
switching person and the start screen; the gates that build an app's
dependencies per instance and per person; and the sync service with its
status, Settings card and banner. Texts of its own in English and
German take the app's name; what only the app can say, it passes in.
Fakes for apps' tests are in testing.dart.

An instance's basics now name the app it serves (`app`, set by the
host's configuration), and an app accepts only an instance of its own.
SerialQueue and CoalescingRunner move into halkyon_core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

packages/halkyon_core/lib/halkyon_core.dart

@@ -5,6 +5,7 @@
 /// - A thin `generateUuid` wrapper for v4 UUID generation.
 /// - A `Logger` interface and basic `ConsoleLogger` implementation.
 /// - The optional `HalkyonException` marker interface.
+/// - `SerialQueue` and `CoalescingRunner`, which run work one at a time.
 library;
 
 // Re-export the clock package directly. Halkyon apps depend on `Clock` for
@@ -12,6 +13,8 @@ library;
 // without needing a separate `clock` dependency.
 export 'package:clock/clock.dart' show Clock, clock;
 
+export 'src/async/coalescing_runner.dart';
+export 'src/async/serial_queue.dart';
 export 'src/exceptions.dart';
 export 'src/logger.dart';
 export 'src/uuid.dart';

packages/halkyon_core/lib/src/async/coalescing_runner.dart

@@ -0,0 +1,50 @@
+import 'dart:async';
+
+/// Runs an action one run at a time: asked again while a run is under way,
+/// it runs once more after it, however often it was asked, so a burst of
+/// changes (a sync brings many) costs one more run, not one each, and an
+/// older result never overtakes a newer one.
+class CoalescingRunner(
+  /// What a run does.
+  final Future<void> Function() _action, {
+
+  /// Hears of a run that failed; a run asked for meanwhile follows anyway.
+  required final void Function(Object error, StackTrace stackTrace) _onError,
+}) {
+  /// The runs under way, one asked for meanwhile included; null while none
+  /// is: a completed future kept from before would run what waits for it in
+  /// the zone it was made in, which a widget test's fake clock never
+  /// reaches.
+  Future<void>? _running;
+
+  /// Whether to run once more after the run under way.
+  var _again = false;
+
+  /// Runs now, or once more after the run under way; completes once no run
+  /// is under way or asked for.
+  Future<void> run() {
+    if (_running case final running?) {
+      _again = true;
+      return running;
+    }
+    final done = Completer<void>();
+    // Set before the first run starts, so a call during it waits its turn.
+    _running = done.future;
+    unawaited(() async {
+      do {
+        _again = false;
+        try {
+          await _action();
+        } on Object catch (error, st) {
+          _onError(error, st);
+        }
+      } while (_again);
+      _running = null;
+      done.complete();
+    }());
+    return done.future;
+  }
+
+  /// Completes once no run is under way or asked for; at once when none is.
+  Future<void> get idle => _running ?? Future<void>.value();
+}

packages/halkyon_core/lib/src/async/serial_queue.dart

@@ -0,0 +1,28 @@
+import 'dart:async';
+
+/// Runs actions one after another, each once the one before is done, failed
+/// or not: a repository's reads and writes, say, so that none meets another
+/// half done.
+class SerialQueue() {
+  // Null while nothing runs: a completed future kept from before would run
+  // what waits for it in the zone it was made in, which a widget test's fake
+  // clock never reaches.
+  Future<void>? _last;
+
+  /// Runs [action] once everything queued before it is done; completes as
+  /// it does.
+  Future<T> run<T>(Future<T> Function() action) async {
+    final previous = _last;
+    final done = Completer<void>();
+    _last = done.future;
+    try {
+      await previous;
+      return await action();
+    } finally {
+      done.complete();
+      if (identical(_last, done.future)) {
+        _last = null;
+      }
+    }
+  }
+}

packages/halkyon_core/test/async/coalescing_runner_test.dart

@@ -0,0 +1,68 @@
+import 'dart:async';
+
+import 'package:halkyon_core/halkyon_core.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('asked again while it runs, it runs once more after, however often '
+      'asked; every caller waits for that too', () async {
+    final log = <String>[];
+    var gate = Completer<void>();
+    var runs = 0;
+    final runner = CoalescingRunner(() async {
+      final run = ++runs;
+      log.add('run $run starts');
+      await gate.future;
+      log.add('run $run ends');
+    }, onError: (_, _) {});
+
+    final first = runner.run();
+    final second = runner.run();
+    final third = runner.run();
+    await pumpEventQueue();
+    expect(log, ['run 1 starts']);
+
+    final firstGate = gate;
+    gate = Completer<void>()..complete();
+    firstGate.complete();
+    await Future.wait([first, second, third]);
+
+    expect(log, ['run 1 starts', 'run 1 ends', 'run 2 starts', 'run 2 ends']);
+    expect(runs, 2);
+  });
+
+  test('a run that fails is reported, and one asked for meanwhile still '
+      'follows', () async {
+    final errors = <Object>[];
+    final gate = Completer<void>();
+    var runs = 0;
+    final runner = CoalescingRunner(() async {
+      runs++;
+      if (runs == 1) {
+        await gate.future;
+        throw StateError('disk unavailable');
+      }
+    }, onError: (error, _) => errors.add(error));
+
+    final first = runner.run();
+    final again = runner.run();
+    gate.complete();
+    await Future.wait([first, again]);
+
+    expect(errors, [isA<StateError>()]);
+    expect(runs, 2);
+  });
+
+  test('idle completes once nothing runs; afterwards a run starts '
+      'afresh', () async {
+    var runs = 0;
+    final runner = CoalescingRunner(() async => runs++, onError: (_, _) {});
+    await runner.idle;
+
+    unawaited(runner.run());
+    await runner.idle;
+    await runner.run();
+
+    expect(runs, 2);
+  });
+}

packages/halkyon_core/test/async/serial_queue_test.dart

@@ -0,0 +1,37 @@
+import 'dart:async';
+
+import 'package:halkyon_core/halkyon_core.dart';
+import 'package:test/test.dart';
+
+void main() {
+  late SerialQueue queue;
+
+  setUp(() => queue = SerialQueue());
+
+  test('runs one action after another, in the order queued', () async {
+    final log = <String>[];
+    final first = Completer<void>();
+
+    final a = queue.run(() async {
+      log.add('a starts');
+      await first.future;
+      log.add('a ends');
+    });
+    final b = queue.run(() async => log.add('b'));
+    await Future<void>.delayed(Duration.zero);
+    expect(log, ['a starts']);
+
+    first.complete();
+    await Future.wait([a, b]);
+    expect(log, ['a starts', 'a ends', 'b']);
+  });
+
+  test('completes with what the action returns, or its error, and goes on '
+      'after an error', () async {
+    final failing = queue.run<int>(() async => throw StateError('broken'));
+    final next = queue.run(() async => 42);
+
+    await expectLater(failing, throwsStateError);
+    expect(await next, 42);
+  });
+}