Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

78.5 KB
Raw Blame
import 'dart:async';
import 'dart:math';

import '../e2ee/bytes.dart';
import '../e2ee/keys.dart';
import 'device_ack.dart';
import 'device_history.dart';
import 'device_log.dart';
import 'group_sync.dart';
import 'viewer_key_store.dart';

export 'device_history.dart'
    show DeviceDepartedCopy, DeviceLogDeparted, DeviceRemovalCopy, DeviceRemovalNotice, historySentence;

/// The account's device key log, on a device with no harness CLI — the viewer's half of
/// cli/src/lib/e2ee/deviceLogSyncer.ts.
///
/// Signing in is what puts this app's key into the log ([register]); every machine the log names is
/// then pinned here with no password, and every machine trusts this app. A backend that rewrites the
/// log or rolls it back FREEZES it here: nothing more is pinned from it until someone reviews what
/// changed ([rebaseline]). A key added after this app joined the log is announced ("New device: X") and
/// stays pending until it is marked seen; what the log says is never read against what the roster holds.
/// "It's mine" here ([dismiss] with `confirm`) is signed and shared beside the log (device_ack.dart), and
/// one another trusted device shared takes a key off `pending` here: the person confirms a new device
/// once, on any of their devices.

/// What `GET /api/device-keys?since=` answered; null from the fetcher when there is no log to read.
typedef DeviceLogFetched = ({String acct, DevLogHead head, List<Object?> entries});

/// `POST /api/device-keys`: the new head, or a refusal (with the current head on `STALE_HEAD`).
typedef DeviceLogAppendAnswer = ({DevLogHead? head, String? error});

typedef DeviceLogFetch = Future<DeviceLogFetched?> Function(int since);
typedef DeviceLogAppend = Future<DeviceLogAppendAnswer?> Function(DevLogEntry entry);

/// `GET /api/device-keys/acks?since=`: the acknowledgements of keys added after entry `since`, unchecked
/// (every one is judged here); null when there are none to read (a backend from before them: 404).
typedef DeviceLogFetchAcks = Future<List<Object?>?> Function(int since);

/// `POST /api/device-keys/acks`: whether the backend kept one this app signed.
typedef DeviceLogPostAck = Future<bool> Function(DevAck ack);

/// Another of the person's trusted devices said "It's mine" for a key that was new here, so it is not New
/// here any more: which device ([by]), what it was called then, and when this app read it. Trusts nothing.
class DeviceLogConfirmed {
  const DeviceLogConfirmed({required this.by, required this.label, required this.at});

  final String by;
  final String label;
  final int at;

  Map<String, Object?> toJson() => {'by': by, 'label': label, 'at': at};

  static DeviceLogConfirmed? fromJson(Object? raw) {
    if (raw is! Map) return null;
    final by = raw['by'], label = raw['label'], at = raw['at'];
    if (by is! String || label is! String || at is! int) return null;
    return DeviceLogConfirmed(by: by, label: label, at: at);
  }
}

class DeviceLogFreeze {
  const DeviceLogFreeze(this.reason, this.at, this.lastGoodHead);

  /// `fork` | `rollback` | `invalid` — see deviceLogStore.ts.
  final String reason;
  final int at;
  final DevLogHead lastGoodHead;

  Map<String, Object?> toJson() => {'reason': reason, 'at': at, 'lastGoodHead': lastGoodHead.toJson()};

  static DeviceLogFreeze? fromJson(Object? raw) {
    if (raw is! Map) return null;
    final reason = raw['reason'], at = raw['at'], head = DevLogHead.fromJson(raw['lastGoodHead']);
    if (reason is! String || at is! int || head == null) return null;
    return DeviceLogFreeze(reason, at, head);
  }
}

class _File {
  _File(
    this.state,
    this.recent,
    this.frozen,
    this.notifiedUpTo, {
    this.joinedSeq,
    this.preLog = const [],
    this.pending = const [],
    this.announced = const [],
    this.suspended = const [],
    this.baselineSeen = true,
    this.looseRemoved = const [],
    this.reviewedSeq,
    this.owner,
    this.joining = false,
    this.departed = const [],
    this.confirmed = const {},
  });

  DevLogState? state;
  List<DevLogEntry> recent;
  DeviceLogFreeze? frozen;
  int notifiedUpTo;

  /// The head seq this app's first read ended at: only an `add` past it is news. Null in a file from
  /// before this existed (migrated on first use).
  int? joinedSeq;

  /// Keys this app trusted when it joined (or migrated): never news.
  List<String> preLog;

  /// New keys nobody has marked as seen yet.
  List<String> pending;

  /// Keys already announced — never twice.
  List<String> announced;

  /// Keys not trusted here after a fork, until [ViewerDeviceLog.rebaseline].
  List<String> suspended;

  /// false until the "Already on your account" panel was dismissed.
  bool baselineSeen;

  /// Removals applied while frozen: never in [recent], which is handed to peers as a chained tail.
  List<DevLogEntry> looseRemoved;

  /// The head seq of the list a person last reviewed ([ViewerDeviceLog.rebaseline]): a key at or
  /// before it was looked at, so a later fork never suspends it.
  int? reviewedSeq;

  /// Which sign-in by hand this file belongs to (see [ViewerDeviceLog.register]). Null in a file from
  /// before this existed.
  String? owner;

  /// true from the fresh write of a log until the first read of it reaches the head (or stops on a
  /// freeze): while set, whatever is verified is what was there at joining — none of it is news.
  bool joining;

  /// New keys removed before anyone looked (oldest first, at most [_departedKept]).
  List<DeviceLogDeparted> departed;

  /// New keys another trusted device confirmed, by pub: "Confirmed on <label>". Only ever the reason a
  /// key left [pending]; it trusts nothing.
  Map<String, DeviceLogConfirmed> confirmed;

  Map<String, Object?> toJson() => {
    'state': state?.toJson(),
    'recent': [for (final e in recent.skip(max(0, recent.length - _recentKept))) e.toJson()],
    'frozen': frozen?.toJson(),
    'notifiedUpTo': notifiedUpTo,
    if (joinedSeq != null) ...{
      'joinedSeq': joinedSeq,
      'preLog': preLog,
      'pending': pending,
      'announced': announced,
      'baselineSeen': baselineSeen,
    },
    if (suspended.isNotEmpty) 'suspended': suspended,
    if (reviewedSeq != null) 'reviewedSeq': reviewedSeq,
    if (owner != null) 'owner': owner,
    if (joining) 'joining': true,
    if (looseRemoved.isNotEmpty)
      'looseRemoved': [for (final e in looseRemoved.skip(max(0, looseRemoved.length - _recentKept))) e.toJson()],
    if (departed.isNotEmpty)
      'departed': [for (final d in departed.skip(max(0, departed.length - _departedKept))) d.toJson()],
    if (confirmed.isNotEmpty) 'confirmed': {for (final e in confirmed.entries) e.key: e.value.toJson()},
  };

  static Map<String, DeviceLogConfirmed> _confirmed(Object? raw) => {
    if (raw is Map)
      for (final e in raw.entries)
        if (e.key is String) e.key as String: ?DeviceLogConfirmed.fromJson(e.value),
  };

  static List<String> _strings(Object? raw) => raw is List ? [for (final v in raw) if (v is String) v] : <String>[];

  static _File parse(Object? raw) {
    if (raw is! Map) return _File(null, [], null, 0);
    final recent = raw['recent'];
    final loose = raw['looseRemoved'];
    return _File(
      DevLogState.fromJson(raw['state']),
      recent is List ? recent.map(DevLogEntry.parse).whereType<DevLogEntry>().toList() : [],
      DeviceLogFreeze.fromJson(raw['frozen']),
      raw['notifiedUpTo'] is int ? raw['notifiedUpTo'] as int : 0,
      joinedSeq: raw['joinedSeq'] is int && (raw['joinedSeq'] as int) >= 0 ? raw['joinedSeq'] as int : null,
      preLog: _strings(raw['preLog']),
      pending: _strings(raw['pending']),
      announced: _strings(raw['announced']),
      suspended: _strings(raw['suspended']),
      baselineSeen: raw['baselineSeen'] is bool ? raw['baselineSeen'] as bool : true,
      looseRemoved: loose is List ? loose.map(DevLogEntry.parse).whereType<DevLogEntry>().toList() : [],
      reviewedSeq: raw['reviewedSeq'] is int && (raw['reviewedSeq'] as int) >= 0 ? raw['reviewedSeq'] as int : null,
      owner: raw['owner'] is String && (raw['owner'] as String).isNotEmpty ? raw['owner'] as String : null,
      joining: raw['joining'] == true,
      departed: DeviceLogDeparted.listFromJson(raw['departed']),
      confirmed: _confirmed(raw['confirmed']),
    );
  }
}

const _recentKept = 64;

/// How many departed keys are kept ([_File.departed]); the oldest goes first.
const _departedKept = 32;

/// How long after a sign-in by hand a read of another account may start the log over: past it, with no
/// read of that account yet, the backend has had the time to pick when it says so.
const _resetWindowMs = 10 * 60 * 1000;
const _appendAttempts = 5;
const _pages = 20;

/// The page cap while a log is first read ([_File.joining]) or reviewed ([ViewerDeviceLog.rebaseline]):
/// 100,000 entries. A first read cut short at [_pages] would take every key past it for news.
const _joinPages = 200;

/// How many other accounts' logs are kept ([ViewerKeyStore.deviceLogArchive]); the oldest goes first.
const _archivedKept = 4;

/// How a sign-in id given to a session from before sign-in ids existed starts: nobody saw that
/// sign-in being made here, so it may take a file over but never starts one over.
const _adoptedSignIn = 'adopted:';

/// One device on the account, for the Devices list.
class DeviceLogRow {
  const DeviceLogRow(
    this.member, {
    required this.fingerprint,
    required this.self,
    this.pending = false,
    this.suspended = false,
    this.confirmed,
  });

  final DevLogMember member;
  final String fingerprint;
  final bool self;

  /// Joined after this app did and nobody marked it as seen.
  final bool pending;

  /// Not trusted here after a fork, until the list is reviewed.
  final bool suspended;

  /// Another trusted device said "It's mine" for it while it was new here; null when none did.
  final DeviceLogConfirmed? confirmed;
}

class DeviceLogListing {
  const DeviceLogListing({
    required this.members,
    required this.frozen,
    required this.frozenPeers,
    this.pending = const [],
    this.suspended = const [],
    this.joinedSeq = 0,
    this.baseline = const [],
    this.baselineSeen = true,
    this.departed = const [],
    this.registerError,
  });

  static const empty = DeviceLogListing(members: [], frozen: null, frozenPeers: []);

  final List<DeviceLogRow> members;
  final DeviceLogFreeze? frozen;

  /// Machines whose own copy of the log is frozen, as their last `group_sync` said.
  final List<String> frozenPeers;

  /// Keys that joined after this app did and nobody marked as seen.
  final List<String> pending;

  /// Keys not trusted here after a fork, until the list is reviewed.
  final List<String> suspended;
  final int joinedSeq;

  /// The keys that were on the account before this app joined (the "Already on your account" list):
  /// active, not this app, at or before [joinedSeq] — plus any key this app already trusted at joining
  /// whose entry came after it (a log cut short at the first read must not hide it).
  final List<String> baseline;

  /// false until the "already on your account" list was acknowledged.
  final bool baselineSeen;

  /// New keys removed before anyone marked them as seen (oldest first): flagged until [ViewerDeviceLog.dismiss]
  /// names them (`pub`, or `pubs`) or clears every one.
  final List<DeviceLogDeparted> departed;

  /// Why the backend last refused to put this app's key into the log (`TOO_MANY`, …), until a
  /// register lands; null when it never did (a lost race or no answer is not a refusal).
  final String? registerError;
}

/// The newest hashes a `group_sync` carries, so a fork can be located.
const _gossipHashes = 64;

/// Where a peer's log first differs from [state]: the first seq, in the window of hashes the peer sent
/// (`theirs['hashes']`, the last of which is `theirs['head']`), whose hash is not ours — only when the
/// entry before it matches (or it is the first), so the split is proven rather than guessed. Null when
/// the peer sent no usable hashes, nothing in the shared window differs, or the split lies before it.
int? devLogDivergence(DevLogState state, Object? theirs) {
  if (theirs is! Map) return null;
  final hashes = theirs['hashes'];
  if (hashes is! List || hashes.isEmpty || hashes.length > 4 * _gossipHashes) return null;
  final window = <int, String>{};
  var prev = 0;
  for (final h in hashes) {
    if (h is! Map) return null;
    final seq = h['seq'], hash = h['hash'];
    if (seq is! int || seq < 1 || hash is! String || hash.length > 128) return null;
    if (prev != 0 && seq != prev + 1) return null;
    prev = seq;
    window[seq] = hash;
  }
  // The window must end where the peer's head is, or it describes some other log.
  final head = DevLogHead.fromJson(theirs['head']);
  if (head == null || head.seq != prev || head.hash != window[prev]) return null;
  final first = window.keys.reduce(min);
  for (final e in window.entries) {
    if (e.key > state.head.seq || state.hashes[e.key - 1] == e.value) continue;
    if (e.key == 1) return 1;
    if (e.key == first) return null;
    return state.hashes[e.key - 2] == window[e.key - 1] ? e.key : null;
  }
  return null;
}


/// What a step under the file lock found to tell the app — said once the lock is let go, since a
/// listener may well read the log again (and signing out waits on the app).
class _Effects {
  final announce = <DevLogMember>[];
  final removed = <DeviceRemovalNotice>[];
  bool signOut = false;
  bool changed = false;
}

class DeviceLogRebaseline {
  const DeviceLogRebaseline(this.head, this.added, this.removed) : logChanged = false, otherAccount = false;

  /// The backend's list is no longer the one that was previewed: nothing was done. Branch on
  /// [logChanged]; [head], [added] and [removed] are empty placeholders then.
  const DeviceLogRebaseline.changed()
    : head = const DevLogHead(0, ''),
      added = const [],
      removed = const [],
      logChanged = true,
      otherAccount = false;

  /// The backend's list is another account's while the live log is the one of the sign-in this app is
  /// under: nothing was done — only a sign-in switches accounts. Branch on [otherAccount]; [head],
  /// [added] and [removed] are empty placeholders then.
  const DeviceLogRebaseline.otherAccount()
    : head = const DevLogHead(0, ''),
      added = const [],
      removed = const [],
      logChanged = false,
      otherAccount = true;

  final DevLogHead head;
  final List<DevLogMember> added;
  final List<DevLogMember> removed;
  final bool logChanged;
  final bool otherAccount;
}

/// What [ViewerDeviceLog.ensureRegistered] found: this app's key already in the log, put there just now,
/// kept out by a frozen log, or still missing (no log to read, the backend down, a refusal).
enum DeviceLogRegistration { active, registered, frozen, missing }

class ViewerDeviceLog {
  ViewerDeviceLog({
    required this.keys,
    required this.fetch,
    required this.append,
    required this.label,
    this.fetchAcks,
    this.postAck,
    this.onAnnounce,
    this.onRemoved,
    this.onSignedOut,
    this.onChanged,
    int Function()? now,
    Future<void> Function(Duration)? sleep,
  }) : _now = now ?? (() => DateTime.now().millisecondsSinceEpoch),
       _sleep = sleep ?? Future.delayed;

  final ViewerKeyStore keys;
  final DeviceLogFetch fetch;
  final DeviceLogAppend append;

  /// The acknowledgements beside the log ("It's mine" said on another device); null: none are read.
  final DeviceLogFetchAcks? fetchAcks;

  /// Where this app's own "It's mine" is shared; null: it stays here.
  final DeviceLogPostAck? postAck;

  /// How this app calls itself in the account's list of devices.
  final String Function() label;

  /// A key joined the account after this app did: "New device: X".
  final void Function(DevLogMember member)? onAnnounce;

  /// A device was taken out of the account after this app joined it (not by this app).
  final void Function(DeviceRemovalNotice notice)? onRemoved;

  /// This app's own key was removed from the account: it is signed out.
  final Future<void> Function()? onSignedOut;

  /// The list, or whether it is frozen, changed.
  final void Function()? onChanged;

  final int Function() _now;
  final Future<void> Function(Duration) _sleep;
  final Map<String, bool> _frozenPeers = {};
  Future<void>? _refreshing;
  final _random = Random();
  final Set<String> _removing = {};

  /// Every entry fetched for the history so far (seq 1..n), this run only: never written to disk.
  List<DevLogEntry> _histCache = [];
  String? _histAcct;

  /// Set while a sign-in by hand registers: this app's old key being removed is then expected, and is
  /// replaced rather than signed out over.
  bool _signingInAgain = false;
  bool _signedOut = false;

  /// Set while [register] runs.
  bool _registering = false;

  /// [DeviceLogListing.registerError]: in memory only, never in the file.
  String? _registerError;

  /// The [register] under way, which [ensureRegistered] lets finish before it judges.
  Future<void>? _registerRun;
  Future<DeviceLogRegistration>? _ensuring;

  /// Moves on with each [beginSignIn]: a read that began after one, outside [register], ends what it
  /// set — a sign-in by hand that never registers must not keep this app's own removal from signing
  /// it out for good.
  int _signInRound = 0;

  /// Which sign-in by hand this app is under ([ViewerKeyStore.signInEpoch]), once known: minted by
  /// [beginSignIn] (or [register] with `freshSignIn`), never anything the backend sends (not the
  /// profile's id either).
  String? _epoch;

  /// Set by [beginSignIn] until [register] takes it: a sign-in by hand waiting to be registered.
  bool _freshPending = false;

  /// The write of the sign-in id [beginSignIn] minted; [register] waits for it.
  Future<void>? _epochSaving;

  /// The sign-in by hand [beginSignIn] minted in this run, until [signedInAs] names its account.
  String? _awaitingAcct;

  /// This app's key is gone from the log: sign out, once.
  Future<void> _signOut() async {
    if (_signedOut) return;
    _signedOut = true;
    await onSignedOut?.call();
  }

  Future<_File> _read() async => _File.parse(await keys.deviceLog());
  Future<void> _write(_File f) => keys.writeDeviceLog(f.toJson());
  Future<String> _selfPub() async => b64e((await keys.identity()).pub);

  /// Read the log and put this app's key into it. Never throws.
  ///
  /// [freshSignIn]: the person has just signed in, by hand. A key the log removed is then spent, not
  /// a reason to sign out — this app may have been signed out by the removal before it could read it
  /// (a revoked session answers 401 first), and signing in again must not end in a second sign-out.
  /// A stored session (the app opening) under a removed key signs out, as it always did.
  ///
  /// A sign-in by hand is also what lets this app's copy of the log move to another account (keeping
  /// the one it leaves, to restore if it comes back) — for a short while after it ([_resetWindowMs]).
  /// Its id is minted by [beginSignIn], which [register] calls itself when it was not called before.
  Future<void> register({bool freshSignIn = false}) {
    final run = _register(freshSignIn: freshSignIn);
    _registerRun = run;
    return run.whenComplete(() {
      if (identical(_registerRun, run)) _registerRun = null;
    });
  }

  Future<void> _register({required bool freshSignIn}) async {
    if (freshSignIn && !_freshPending) beginSignIn(fresh: true);
    final fresh = _freshPending;
    _freshPending = false;
    _signingInAgain = fresh;
    _signedOut = false;
    _registering = true;
    try {
      await _epochSaving;
      await refresh();
      var identity = await keys.identity();
      var pub = b64e(identity.pub);
      final name = _clip(label());
      for (var attempt = 0; attempt < _appendAttempts; attempt++) {
        final file = await _read();
        final state = file.state;
        if (state == null || file.frozen != null) return;
        if (state.removed.contains(pub)) {
          if (!fresh) {
            await _signOut();
            return;
          }
          await keys.forgetIdentity();
          await refresh();
          identity = await keys.identity();
          pub = b64e(identity.pub);
          continue;
        }
        final mine = state.active[pub];
        if (mine != null) _registerError = null;
        if (mine != null && (mine.label == name || mine.kind != 'viewer')) return;
        final entry = await signDevLogEntry(
          nextDevLogEntry(state, op: 'add', pub: pub, kind: 'viewer', machineId: '', label: name, signer: pub, at: _now()),
          identity,
        );
        final answer = await append(entry);
        if (answer == null) return;
        if (answer.error == null) {
          _registerError = null;
          await refresh();
          return;
        }
        if (answer.error != 'STALE_HEAD') {
          _registerError = answer.error;
          return;
        }
        await refresh();
        await _sleep(Duration(milliseconds: 200 + _random.nextInt(800) * (attempt + 1)));
      }
    } catch (_) {
      // [ensureRegistered] tries again: a machine refusing this app, a socket back, the app in front.
    } finally {
      _signingInAgain = false;
      _registering = false;
    }
  }

  /// Put this app's key into the log when it is not there yet. [register] can end without it — no log
  /// to read, the backend down, five lost races, a refusal — and then no machine will trust this app,
  /// so this is asked again whenever that matters: a machine refusing this app, a socket coming back,
  /// the app in front again. A frozen log is left as it is: only a review unfreezes it. Concurrent
  /// calls share one run. Never throws.
  Future<DeviceLogRegistration> ensureRegistered() =>
      _ensuring ??= _ensureRegistered().whenComplete(() => _ensuring = null);

  Future<DeviceLogRegistration> _ensureRegistered() async {
    try {
      // A register already under way (the boot's) decides first: a second one beside it would race it.
      await _registerRun;
      await refresh();
      if (await _registration() case final known?) return known;
      await register();
      return await _registration() == DeviceLogRegistration.active
          ? DeviceLogRegistration.registered
          : DeviceLogRegistration.missing;
    } catch (_) {
      return DeviceLogRegistration.missing;
    }
  }

  /// Where this app's key stands in the file: null when it is not there and nothing keeps it out.
  Future<DeviceLogRegistration?> _registration() async {
    final file = await _read();
    if (file.state?.active.containsKey(await _selfPub()) ?? false) return DeviceLogRegistration.active;
    return file.frozen != null ? DeviceLogRegistration.frozen : null;
  }

  /// The app knows who is signed in — call it synchronously, before anything that reads the log (a
  /// restored pane, a machine list, a connection) can start, then [register]. [fresh]: the person
  /// signed in by hand just now (`DirectAuth.consumeFreshSignIn()`); its id is minted here, so a read
  /// already on its way judges by this sign-in, not the one before. A stored session (the app opening)
  /// is not fresh: nothing is minted.
  void beginSignIn({required bool fresh}) {
    _signedOut = false;
    _freshPending = fresh;
    // A removal of this app's old key read before [register] runs is then expected, not a sign-out —
    // for the read that comes first ([_doRefresh] ends it), or until [register] takes over.
    _signingInAgain = fresh;
    _signInRound++;
    _awaitingAcct = null;
    if (!fresh) return;
    final previous = _epoch;
    final minted = _mintEpoch();
    _epoch = minted;
    _awaitingAcct = minted;
    _epochSaving = keys.writeSignInEpoch(minted).then(
      (_) {},
      onError: (Object _) {
        // Not kept, not used: after a restart the file would be another sign-in's than the store's.
        if (_epoch == minted) _epoch = previous;
      },
    );
  }

  /// Who the person just signed in as, by hand: the profile's user id (`/api/auth/me`), which is what
  /// the log names its account by. Kept beside the sign-in id, so the first read of that account
  /// starts the list over whenever it comes ([_mayStartOver]). Only for the sign-in by hand
  /// [beginSignIn] minted in this run — a stored session (the app opening) records nothing. Never
  /// throws.
  Future<void> signedInAs(String acct) async {
    final epoch = _awaitingAcct;
    if (epoch == null || acct.isEmpty) return;
    _awaitingAcct = null;
    try {
      await _epochSaving;
      if (_epoch == epoch) await keys.writeSignInAcct(epoch, acct);
    } catch (_) {
      // Not recorded: the sign-in falls back to the short window.
    }
  }

  /// Read and verify whatever the log gained. Concurrent calls share one read. Never throws.
  Future<void> refresh() => _refreshing ??= _doRefresh().catchError((Object _) {}).whenComplete(() => _refreshing = null);

  /// The tail of the queue every read-modify-write of the file waits in. A refresh, a peer's tail, a
  /// dismissal and a review each read the file, change it and write it back; two of them interleaved
  /// would write the older read over the newer one — a head rolled back, an announcement forgotten
  /// and made twice, a dismissal undone.
  Future<void> _fileQueue = Future.value();

  /// Run [body] alone against the file — within this instance: two instances over one store (two web
  /// tabs) do not see each other's lock and can still interleave. [body] must not wait on anything
  /// that takes the lock itself (and nothing the app is told runs inside it: see [_Effects]).
  Future<T> _locked<T>(Future<T> Function() body) {
    final before = _fileQueue;
    final done = Completer<void>();
    _fileQueue = done.future;
    return before.then((_) => body()).whenComplete(() => done.complete());
  }

  /// Tell the app what a step under the lock decided, once the lock is let go.
  Future<void> _fire(_Effects e) async {
    for (final m in e.announce) {
      onAnnounce?.call(m);
    }
    for (final n in e.removed) {
      onRemoved?.call(n);
    }
    if (e.signOut) await _signOut();
    if (e.changed) onChanged?.call();
  }

  /// A sign-in id: random, then `@` and when it was made (ms) — see [_mayStartOver].
  String _mintEpoch() =>
      '${[for (var i = 0; i < 16; i++) _secure.nextInt(256).toRadixString(16).padLeft(2, '0')].join()}@${_now()}';
  static final _secure = Random.secure();

  /// Whether [local] — a sign-in by hand the file is not yet the log of — may start it over for [acct]:
  /// never an adopted one; the account the profile named for it ([signedInAs]) whenever its first read
  /// comes, and no other; with none named, any only shortly after it was made. A backend that holds the
  /// log back after a sign-in must not keep that door open, to name another account days later.
  Future<bool> _mayStartOver(String local, String acct) async {
    if (local.startsWith(_adoptedSignIn)) return false;
    try {
      final named = await keys.signInAcct(local);
      if (named != null) return named == acct;
    } catch (_) {
      // Unreadable: the window alone decides.
    }
    final made = RegExp(r'@(\d{1,15})$').firstMatch(local);
    if (made == null) return false;
    return (_now() - int.parse(made.group(1)!)).abs() <= _resetWindowMs;
  }

  /// Whether the log this app holds is the one of the sign-in it is under — false while it may still be
  /// the account just left, before the first read under a new sign-in. No log yet is nobody's: true.
  /// Never throws (false when the file cannot be read).
  Future<bool> ownsLog() async {
    try {
      final file = await _read();
      return file.state == null || await _ownsFile(file);
    } catch (_) {
      return false;
    }
  }

  /// Whether [file] is the log of the sign-in this app is under (or that cannot be told). Until a read
  /// of it under a new sign-in it may be the account just left: what a machine gossips is not judged
  /// against it — a machine of the new account would read as a fork of the old one.
  Future<bool> _ownsFile(_File file) async {
    final local = await _localOwner();
    return local == null || file.owner == local;
  }

  /// The sign-in by hand this app is under; a session from before sign-in ids existed is given one,
  /// adopted ([_adoptedSignIn]). Null when the store cannot be read.
  Future<String?> _localOwner() async {
    if (_epoch case final epoch?) return epoch;
    try {
      final stored = await keys.signInEpoch();
      if (stored != null && stored.isNotEmpty) return _epoch ??= stored;
      final adopted = '$_adoptedSignIn${_mintEpoch()}';
      await keys.writeSignInEpoch(adopted);
      return _epoch ??= adopted;
    } catch (_) {
      return null;
    }
  }

  /// The first read of the log is over, however it ended: what is verified from here on is news.
  Future<void> _endJoin() => _locked(() async {
    final file = await _read();
    if (!file.joining) return;
    file.joining = false;
    await _write(file);
  });

  /// The logs of accounts this app was signed in to before, by account id.
  Future<Map<String, Object?>> _archived() async {
    try {
      return await keys.deviceLogArchive();
    } catch (_) {
      return {};
    }
  }

  /// Keep [file] — the log of an account this app is leaving — to restore if it comes back, with what
  /// this app trusted under it ([trust]: [ViewerKeyStore.trustSnapshot]). [keep]: the account about
  /// to be restored, never the one dropped to make room — it was, when it was the oldest kept, and
  /// coming back to it then started its list over. Under the lock.
  Future<void> _archiveIn(_File file, {Map<String, Object?>? trust, String? keep}) async {
    final acct = file.state?.acct;
    if (acct == null) return;
    final all = await _archived()
      ..remove(acct);
    all[acct] = {...file.toJson(), 'trust': ?trust};
    while (all.length > _archivedKept + (all.containsKey(keep) ? 1 : 0)) {
      all.remove(all.keys.firstWhere((k) => k != keep));
    }
    await keys.writeDeviceLogArchive(all);
  }

  /// The kept log of [acct], made the live file (this sign-in's: [owner]) and only then taken out of
  /// the archive — a crash in between leaves it in both, never in neither. Null when there is none.
  /// With [swapTrust] (another account's log was live), what this app trusted under [acct] is trusted
  /// again — and nothing of the account left. Under the lock.
  Future<_File?> _restoreIn(String acct, String? owner, {required bool swapTrust}) async {
    final raw = (await _archived())[acct];
    final kept = _File.parse(raw);
    if (kept.state?.acct != acct) return null;
    kept.owner = owner ?? kept.owner;
    await _carrySuspensionsIn(kept);
    await _write(kept);
    if (swapTrust) {
      final trust = _trustOf(raw);
      await keys.writeTrust(trust ?? const {});
      // Kept by a build that did not keep trust with it: what the log names is trusted again.
      if (trust == null && kept.frozen == null) await _trust(kept.state!.active.values.toList());
    }
    final all = await _archived()
      ..remove(acct);
    await keys.writeDeviceLogArchive(all);
    return kept;
  }

  /// [file], with every key a fork suspended in another account's kept log, and active in this one,
  /// suspended (and new) here as well: it is not trusted either way, so the list says so — and "It's
  /// mine" lifts it, everywhere (a review of this list does not: it never showed that suspension).
  /// Under the lock.
  Future<void> _carrySuspensionsIn(_File file) async {
    final state = file.state;
    if (state == null) return;
    final selfPub = await _selfPub();
    final carried = [
      for (final k in await _archivedSuspended())
        if (state.active.containsKey(k) && k != selfPub && !file.suspended.contains(k)) k,
    ];
    if (carried.isEmpty) return;
    file
      ..suspended = [...file.suspended, ...carried]
      ..pending = {...file.pending, ...carried}.toList();
  }

  /// What this app trusted under a kept log ([_archiveIn]); null in one kept before that existed.
  static Map<Object?, Object?>? _trustOf(Object? kept) =>
      kept is Map && kept['trust'] is Map ? kept['trust'] as Map<Object?, Object?> : null;

  /// A suspension lifted here holds for every kept account too: none of them keeps [pubs] out. Under
  /// the lock.
  Future<void> _unsuspendArchivedIn(Iterable<String> pubs) async {
    final lift = pubs.toSet();
    final all = await _archived();
    var changed = false;
    for (final e in all.entries.toList()) {
      final f = _File.parse(e.value);
      if (!f.suspended.any(lift.contains)) continue;
      f.suspended = [for (final k in f.suspended) if (!lift.contains(k)) k];
      all[e.key] = {...f.toJson(), 'trust': ?_trustOf(e.value)};
      changed = true;
    }
    if (changed) await keys.writeDeviceLogArchive(all);
  }

  /// [gone], just taken out by [e], kept flagged: it was new here and nobody had looked at it yet.
  DeviceLogDeparted _departedOf(DevLogMember gone, DevLogEntry e, String signerLabel) => DeviceLogDeparted(
    pub: gone.pub,
    label: gone.label,
    kind: gone.kind,
    machineId: gone.machineId,
    fingerprint: fingerprint(b64d(gone.pub)),
    addedAt: gone.addedAt,
    removedAt: e.at,
    removedBy: e.signer,
    removedByLabel: signerLabel,
    selfRemoved: e.signer == gone.pub,
  );

  /// [prev] plus [more] (a key once, at its newest), the oldest dropped past [_departedKept].
  List<DeviceLogDeparted> _withDeparted(List<DeviceLogDeparted> prev, List<DeviceLogDeparted> more) {
    if (more.isEmpty) return prev;
    final pubs = {for (final d in more) d.pub};
    final all = [for (final d in prev) if (!pubs.contains(d.pub)) d, ...more];
    return all.skip(max(0, all.length - _departedKept)).toList();
  }

  /// The kept log of [acct], left in the archive; null when there is none.
  Future<_File?> _archivedFileIn(String acct) async {
    final kept = _File.parse((await _archived())[acct]);
    return kept.state?.acct == acct ? kept : null;
  }

  /// What a review ([rebaseline]) takes out that was new here and never looked at: a key pending in
  /// [base] that the reviewed list does not keep — and a key the list added and removed again at
  /// entries this app never verified (while it was frozen) — stays flagged as departed.
  List<DeviceLogDeparted> _reviewDeparted(
    _File base,
    DevLogState next,
    List<DevLogEntry> parsed,
    List<DevLogMember> removed,
    String selfPub,
    Set<String> pre,
  ) {
    final verified = base.state;
    if (verified == null) return [];
    final known = <String, ({String label, String kind})>{};
    final adds = <String, DevLogEntry>{};
    final out = <String, DeviceLogDeparted>{};
    for (final e in [...parsed]..sort((a, b) => a.seq.compareTo(b.seq))) {
      if (e.op == 'add') {
        if (!known.containsKey(e.pub)) adds[e.pub] = e; // added (not renamed)
        known[e.pub] = (label: e.label, kind: e.kind);
        continue;
      }
      final was = removed.where((m) => m.pub == e.pub).firstOrNull;
      final add = adds[e.pub];
      final label = known[e.pub]?.label;
      known.remove(e.pub);
      if (e.pub == selfPub || next.active[e.pub] != null) continue;
      // Added at an entry this app never verified, and gone again before it could see it.
      final unseen = was == null &&
          add != null &&
          (add.seq > verified.hashes.length || verified.hashes[add.seq - 1] != devLogHash(add)) &&
          !pre.contains(e.pub);
      if ((was != null && base.pending.contains(e.pub)) || unseen) {
        final member = was ??
            DevLogMember(pub: e.pub, kind: add!.kind, machineId: add.machineId, label: label ?? add.label, addedAt: add.at, seq: add.seq);
        out[e.pub] = _departedOf(member, e, known[e.signer]?.label ?? '');
      }
    }
    // Pending here, and not on the reviewed list at all (a branch the backend no longer serves).
    for (final m in removed) {
      if (out.containsKey(m.pub) || m.pub == selfPub || !base.pending.contains(m.pub)) continue;
      out[m.pub] = DeviceLogDeparted(
        pub: m.pub,
        label: m.label,
        kind: m.kind,
        machineId: m.machineId,
        fingerprint: fingerprint(b64d(m.pub)),
        addedAt: m.addedAt,
        removedAt: _now(),
        removedBy: '',
        removedByLabel: '',
        selfRemoved: false,
      );
    }
    return [...out.values];
  }

  /// Every key a fork suspended in another account's kept log: no other account's log brings it back.
  Future<Set<String>> _archivedSuspended() async => {
    for (final f in (await _archived()).values) ..._File.parse(f).suspended,
  };

  Future<_File> _marks() => _locked(_marksIn);

  /// [_marks], for a caller already holding the lock: the file, with the joined point filled in for one
  /// written before it existed (or by a client that dropped it) — everything up to what was already
  /// announced is then known, as it was.
  Future<_File> _marksIn() async {
    final file = await _read();
    if (file.state == null || file.joinedSeq != null) return file;
    file.joinedSeq = file.notifiedUpTo;
    file.preLog = (await _knownPubs()).toList();
    file.pending = [];
    file.announced = [];
    file.baselineSeen = true;
    await _write(file);
    return file;
  }

  Future<void> _doRefresh() async {
    // A sign-in by hand waiting for [register]: this read is the one its old key's removal is expected
    // in. After it, with no [register] under way, a removal of this app's key signs out again.
    final round = _signInRound;
    final expecting = _signingInAgain;
    try {
      await _readPages();
    } finally {
      // However the read ended — at the head, on a freeze, or cut short (no answer, the page cap) — the
      // first read of a log is over: what is verified from here on is news. Held open, a backend that
      // stalls the second page would have every key it adds later taken for one there at joining.
      await _endJoin();
      if (expecting && !_registering && round == _signInRound) _signingInAgain = false;
    }
    // After the entries, so a key added and confirmed while this app was closed is first announced, as
    // every new key is — the one-time "New device: X" never waits on, or is skipped for, anyone's word —
    // and only then taken off the list.
    await _applyAcks();
  }

  /// [marks] cut to the keys still active, as a file's [_File.confirmed].
  Map<String, DeviceLogConfirmed> _keptConfirmed(Map<String, DeviceLogConfirmed> marks, DevLogState state) => {
    for (final e in marks.entries)
      if (state.active.containsKey(e.key)) e.key: e.value,
  };

  /// The keys an acknowledgement could take off `pending` in [file]: new here, still active, not
  /// suspended, not this app — and none at all from a log that is frozen or not this sign-in's.
  Future<List<DevLogMember>> _ackable(_File file) async {
    final state = file.state;
    if (state == null || file.frozen != null || !await _ownsFile(file)) return const [];
    final selfPub = await _selfPub();
    final suspended = await suspendedPubs();
    return [
      for (final k in file.pending.toSet())
        if (state.active[k] case final m? when m.pub != selfPub && !suspended.contains(k)) m,
    ];
  }

  /// Take off `pending` every key another of the person's trusted devices said "It's mine" for
  /// (device_ack.dart), and remember which device did ("Confirmed on <label>").
  ///
  /// The backend's word counts for nothing: each acknowledgement must check out against the log as THIS
  /// app verified it ([checkDevAck]: signature, a signer active on it, the key added at the entry it
  /// names), and against this app's own marks. The key must still be new here and not suspended — an
  /// acknowledgement never lifts a suspension; only the person does, here, with "It's mine" on that very
  /// device. The signer must be a device this app trusts: not new here itself (two new devices must not
  /// vouch for each other), not suspended, not removed (a departed key is not active), not tombstoned in
  /// the trust group, and not this app (its own "It's mine" already took the key off). Nothing is read
  /// while the log is frozen or not yet this sign-in's. Never throws.
  Future<void> _applyAcks() async {
    final read = fetchAcks;
    if (read == null) return;
    try {
      final candidates = await _ackable(await _read());
      // Nothing new here: nothing to ask (and no request at all, on every read, for most of an app's life).
      if (candidates.isEmpty) return;
      final raw = await read(candidates.map((m) => m.seq).reduce(min) - 1);
      if (raw == null || raw.isEmpty) return;
      final confirmed = await _locked(() async {
        // Judged against the file as it is NOW: the log may have moved, or a key been looked at, meanwhile.
        final file = await _read();
        final state = file.state;
        final open = {for (final m in await _ackable(file)) m.pub};
        final out = <String, DeviceLogConfirmed>{};
        if (state == null || open.isEmpty) return out;
        final selfPub = await _selfPub();
        final pending = file.pending.toSet();
        final suspended = await suspendedPubs();
        final roster = GroupRoster.parse(await keys.groupRoster());
        final inRoster = {for (final m in roster.members) m.pub};
        final tombstoned = {for (final t in roster.removed) if (!inRoster.contains(t.pub)) t.pub};
        for (final r in raw) {
          final ack = (await checkDevAck(state, r)).ack;
          if (ack == null || !open.contains(ack.pub) || out.containsKey(ack.pub)) continue;
          if (ack.signer == selfPub ||
              pending.contains(ack.signer) ||
              suspended.contains(ack.signer) ||
              tombstoned.contains(ack.signer)) {
            continue;
          }
          out[ack.pub] = DeviceLogConfirmed(by: ack.signer, label: state.active[ack.signer]!.label, at: _now());
        }
        if (out.isEmpty) return out;
        file
          ..pending = [for (final k in file.pending) if (!out.containsKey(k)) k]
          ..confirmed = _keptConfirmed({...file.confirmed, ...out}, state);
        await _write(file);
        return out;
      });
      if (confirmed.isNotEmpty) onChanged?.call();
    } catch (_) {
      // Unreadable now: the list stays as it was, and the next read asks again.
    }
  }

  Future<void> _readPages() async {
    await _marks();
    var bootstrap = ((await _read()).state?.head.seq ?? 0) == 0;
    // The file's own `joining` decides, each page: the first page of a fresh log is what sets it.
    for (var page = 0; page < ((await _read()).joining ? _joinPages : _pages); page++) {
      final seen = (await _read()).state;
      final since = seen?.head.seq ?? 0;
      final got = await fetch(since);
      if (got == null) return;
      // A head that is not a position is the backend lying (or broken): nothing to verify it against.
      if (!_isPosition(got.head.seq)) return;
      final effects = _Effects();
      // Whether to read another page.
      final more = await _locked(() async {
        var file = await _marksIn();
        final local = await _localOwner();
        var reset = file.state == null;
        if (!reset) {
          final signedInAgain = local != null && file.owner != local;
          if (file.state!.acct != got.acct) {
            // Another account only after a sign-in by hand here. Otherwise it is the backend saying so
            // — and starting over would clear every mark a fork put on the list, the real log then
            // adopted whole.
            if (local == null || !signedInAgain || !await _mayStartOver(local, got.acct)) {
              await _freezeIn(file, 'invalid', effects);
              return false;
            }
            reset = true;
          } else if (signedInAgain) {
            // Signed in again to the same account: the same list, now this sign-in's.
            file.owner = local;
            await _write(file);
          }
        }
        if (reset) {
          // Another account's log was live: it is kept with what this app trusted under it, none of
          // which this account's machines are told of or trusted by. A first read keeps the pins: they
          // are links made before the log existed.
          final leaving = file.state != null;
          if (leaving) {
            await _archiveIn(file, trust: await keys.trustSnapshot(), keep: got.acct);
            _frozenPeers.clear();
          }
          // Back to an account this app was signed in to before: its log as verified then, and every
          // mark on it (frozen, suspended, pending), go on from where they were.
          final kept = await _restoreIn(got.acct, local, swapTrust: leaving);
          if (kept != null) {
            bootstrap = (kept.state?.head.seq ?? 0) == 0;
            return true;
          }
          // First read, or signed in to another account here: that account's log starts from nothing.
          // `joinedSeq` starts at 0 and follows the head of each page this app VERIFIES ([_acceptIn]):
          // never the head the backend merely claims, or it could park it far ahead and have every key
          // it forges below that adopted without a word. `preLog` is what was trusted already — under
          // this account, so nothing when another one's log was live.
          if (leaving) await keys.writeTrust(const {});
          file = _File(
            DevLogState.empty(got.acct),
            [],
            null,
            0,
            joinedSeq: 0,
            preLog: (await _knownPubs()).toList(),
            baselineSeen: false,
            joining: true,
            owner: local,
          );
          await _write(file);
          bootstrap = true;
          if (got.head.seq == 0) return false;
          if (since != 0) return true;
        } else if (seen == null || seen.acct != file.state!.acct || seen.head != file.state!.head) {
          // The log moved here while this page was on its way (a peer handed over its tail): the page
          // answers a question nobody is asking any more — judged against the newer head it would read
          // as a rollback, or as entries out of order. Ask again from where the log is now.
          return true;
        }
        final state = file.state!;
        if (file.frozen != null) {
          await _looseRemovalsIn(file, got.entries, effects);
          return false;
        }
        if (got.head.seq < state.head.seq) {
          await _freezeIn(file, 'rollback', effects);
          return false;
        }
        if (got.head.seq == state.head.seq) {
          if (got.head.hash != state.head.hash) await _freezeIn(file, 'fork', effects);
          return false;
        }
        if (got.entries.isEmpty) {
          await _freezeIn(file, 'invalid', effects);
          return false;
        }
        if (!await _acceptIn(file, got.entries, bootstrap, effects)) return false;
        return file.state!.head.seq < got.head.seq;
      });
      await _fire(effects);
      if (!more) return;
    }
  }

  /// [keys] cut to the ones still active — the marks never outlive the key.
  List<String> _prune(List<String> keys, DevLogState state) => [
    for (final k in keys.toSet())
      if (state.active.containsKey(k)) k,
  ];

  /// What each active key in [state] is called now, to be walked forward through entries.
  Map<String, ({String label, String kind})> _knownOf(DevLogState state) => {
    for (final m in state.active.values) m.pub: (label: m.label, kind: m.kind),
  };

  /// The notice for a `remove`, or null when there is nothing to say: this app's own removal, its own
  /// key, or a removal from before it joined. [known] says what each key was called, and what kind it
  /// was, BEFORE this removal — the remove entry's own label and kind are the signer's to pick, so they
  /// are never what the person is told.
  DeviceRemovalNotice? _removalNotice(
    DevLogEntry e,
    int joinedSeq,
    String selfPub,
    List<String> pending,
    Map<String, ({String label, String kind})> known,
  ) {
    if (e.op != 'remove' || e.seq <= joinedSeq || e.pub == selfPub || e.signer == selfPub) return null;
    final was = known[e.pub];
    return DeviceRemovalNotice(
      pub: e.pub,
      label: was?.label ?? e.label,
      kind: was?.kind ?? e.kind,
      fingerprint: fingerprint(b64d(e.pub)),
      signer: e.signer,
      signerLabel: known[e.signer]?.label ?? '',
      signerFingerprint: fingerprint(b64d(e.signer)),
      signerPending: pending.contains(e.signer),
      selfRemoved: e.signer == e.pub,
      at: _now(),
    );
  }

  /// The entries a peer handed over that this app lacks, applied under the lock — judged against the
  /// head the file has by then, which a refresh may have moved since the peer was heard.
  Future<bool> _acceptFromPeer(List<Object?> entries) async {
    final effects = _Effects();
    final ok = await _locked(() async {
      final file = await _marksIn();
      final state = file.state;
      if (state == null || file.frozen != null) return false;
      final missing = [
        for (final e in entries)
          if ((DevLogEntry.parse(e)?.seq ?? 0) > state.head.seq) e,
      ];
      if (missing.isEmpty) return true;
      return _acceptIn(file, missing, false, effects);
    });
    await _fire(effects);
    return ok;
  }

  /// Apply [entries] to [file] and write it; under the lock. What the app is told goes in [effects].
  Future<bool> _acceptIn(_File file, List<Object?> entries, bool bootstrap, _Effects effects) async {
    // While the first read of this log is open (a peer's tail can arrive between its pages too):
    // whatever is verified before it reaches the head is what was there at joining.
    final joining = file.joining;
    final DevLogApplied applied;
    try {
      applied = await applyDevLogEntries(file.state!, entries);
    } on DevLogError catch (err) {
      await _freezeIn(file, err.code == 'BROKEN_CHAIN' || err.code == 'OUT_OF_ORDER' ? 'fork' : 'invalid', effects);
      return false;
    }
    final selfPub = await _selfPub();
    // While joining, everything this page verified is what was there before: the joined point moves up
    // to the verified head (never past it), and none of it is news.
    final joinedSeq = joining ? applied.state.head.seq : file.joinedSeq ?? 0;
    final pre = file.preLog.toSet();
    final parsed = entries.map(DevLogEntry.parse).whereType<DevLogEntry>().toList();
    // News is decided from the log alone: an `add` past the point this app joined, for a key it did not
    // already trust then. What the roster or the pins hold now says nothing — a key can reach them
    // (over `group_sync`) before this app reads the entry that adds it.
    final news = [
      for (final m in applied.added)
        if (m.seq > joinedSeq && m.pub != selfPub && !pre.contains(m.pub)) m,
    ];
    final pendingNow = [...file.pending, for (final m in news) m.pub];
    // Walk the entries in order: a removal is described by what the key was called when it was removed.
    final known = _knownOf(file.state!);
    final notices = <DeviceRemovalNotice>[];
    final gone = {for (final m in applied.removed) m.pub: m};
    final departed = <DeviceLogDeparted>[];
    for (final e in [...parsed]..sort((a, b) => a.seq.compareTo(b.seq))) {
      if (e.op == 'add') {
        known[e.pub] = (label: e.label, kind: e.kind);
      } else {
        final n = _removalNotice(e, joinedSeq, selfPub, pendingNow, known);
        if (n != null) notices.add(n);
        // A new key nobody looked at, gone again (even within this page): it stays flagged.
        final member = gone[e.pub];
        if (member != null && pendingNow.contains(e.pub) && e.pub != selfPub) {
          departed.add(_departedOf(member, e, known[e.signer]?.label ?? ''));
        }
        known.remove(e.pub);
      }
    }
    final toAnnounce = [
      for (final m in news)
        if (!file.announced.contains(m.pub)) m,
    ];
    // A key taken into the "already on your account" list after that list was acknowledged: show it.
    if (joining && applied.added.any((m) => m.pub != selfPub)) file.baselineSeen = false;
    file
      ..state = applied.state
      ..joinedSeq = joinedSeq
      ..recent = [...file.recent, ...parsed]
      ..frozen = null
      ..notifiedUpTo = applied.state.head.seq
      ..pending = _prune(pendingNow, applied.state)
      ..announced = _prune([...file.announced, for (final m in toAnnounce) m.pub], applied.state)
      ..suspended = _prune(file.suspended, applied.state)
      ..departed = _withDeparted(file.departed, departed)
      ..confirmed = _keptConfirmed(file.confirmed, applied.state);
    await _carrySuspensionsIn(file);
    await _write(file);
    await _trust(bootstrap ? applied.state.active.values.toList() : [...applied.added, ...applied.relabeled]);
    for (final m in applied.removed) {
      await _drop(m);
    }
    effects.announce.addAll(toAnnounce);
    effects.removed.addAll(notices);
    if (applied.state.removed.contains(selfPub) && !_signingInAgain) effects.signOut = true;
    effects.changed = true;
    return true;
  }

  /// What this app trusts right now — its pins and its trust group — snapshotted once, when it joins
  /// the log (or migrates), so what it already knew then is never news.
  Future<Set<String>> _knownPubs() async {
    final roster = GroupRoster.parse(await keys.groupRoster());
    return {
      for (final p in await keys.peers()) b64e(p.pub),
      for (final m in roster.members) m.pub,
    };
  }

  /// Pin every machine the log adds, and put it in the trust group this app swaps with machines, so
  /// a machine that predates the log hears of it too. A removal the group made first stands.
  Future<void> _trust(List<DevLogMember> members) async {
    final selfPub = await _selfPub();
    final stored = GroupRoster.parse(await keys.groupRoster());
    final inRoster = {for (final m in stored.members) m.pub};
    final tombstoned = {for (final t in stored.removed) if (!inRoster.contains(t.pub)) t.pub};
    final suspended = await suspendedPubs();
    final now = _now();
    final adopt = [
      for (final m in members)
        if (m.pub != selfPub && !tombstoned.contains(m.pub) && !suspended.contains(m.pub)) m,
    ];
    final incoming = [
      for (final m in adopt)
        ?GroupMember.tryParse({
          'pub': m.pub,
          'kind': m.kind,
          'label': m.label,
          'at': min(m.addedAt, now),
          if (m.machineId.isNotEmpty) 'machineId': m.machineId,
        }),
    ];
    if (incoming.isNotEmpty) {
      final merged = mergeGroupRoster(stored, GroupRoster(incoming, const []), selfPub);
      await keys.writeGroupRoster(merged.roster.toJson());
    }
    for (final m in adopt) {
      if (m.kind != 'machine') continue;
      final current = await keys.peer(m.machineId);
      if (current != null && b64e(current.pub) == m.pub) continue;
      await keys.pin(m.machineId, b64d(m.pub), label: m.label);
    }
    // A removal the group made before the log existed must not be undone by the log. Not awaited:
    // this runs inside a read of the log, and a removal reads the log again when it lands — waiting
    // for it here would wait for this very read to finish.
    final state = (await _read()).state;
    if (state != null && state.active[selfPub] != null) {
      for (final pub in tombstoned) {
        if (state.active[pub] != null && !_removing.contains(pub)) unawaited(remove(pub));
      }
    }
  }

  Future<void> _drop(DevLogMember m) async {
    final selfPub = await _selfPub();
    final stored = GroupRoster.parse(await keys.groupRoster());
    final merged = mergeGroupRoster(stored, GroupRoster(const [], [GroupTombstone(m.pub, _now())]), selfPub);
    await keys.writeGroupRoster(merged.roster.toJson());
    if (m.kind == 'machine') {
      final current = await keys.peer(m.machineId);
      if (current != null && b64e(current.pub) == m.pub) await keys.unlink(m.machineId);
    }
  }

  /// While frozen, a removal still counts — if a key this app trusts signed it. A key a fork suspended
  /// is not trusted here, so what it signs does not count either.
  /// Under the lock.
  Future<void> _looseRemovalsIn(_File file, List<Object?> entries, _Effects effects) async {
    final state = file.state;
    if (state == null) return;
    final selfPub = await _selfPub();
    final joinedSeq = file.joinedSeq ?? 0;
    final suspended = file.suspended.toSet();
    final known = _knownOf(state);
    final loose = <DevLogEntry>[];
    final notices = <DeviceRemovalNotice>[];
    final departed = <DeviceLogDeparted>[];
    for (final raw in entries) {
      final e = DevLogEntry.parse(raw);
      if (e == null || e.op != 'remove' || state.active[e.signer] == null || suspended.contains(e.signer)) continue;
      final target = state.active[e.pub];
      if (target == null) continue;
      if (!await verifySignature(b64d(e.signer), devLogMessage(e), b64d(e.sig))) continue;
      final notice = _removalNotice(e, joinedSeq, selfPub, file.pending, known);
      if (file.pending.contains(e.pub) && e.pub != selfPub) departed.add(_departedOf(target, e, known[e.signer]?.label ?? ''));
      state.active.remove(e.pub);
      state.removed.add(e.pub);
      await _drop(target);
      loose.add(e);
      if (notice != null) notices.add(notice);
    }
    if (loose.isEmpty) return;
    file
      ..looseRemoved = [...file.looseRemoved, ...loose]
      ..pending = _prune(file.pending, state)
      ..announced = _prune(file.announced, state)
      ..suspended = _prune(file.suspended, state)
      ..departed = _withDeparted(file.departed, departed);
    await _write(file);
    effects.removed.addAll(notices);
    effects.changed = true;
  }

  Future<void> _freeze(String reason) async {
    final effects = _Effects();
    await _locked(() async => _freezeIn(await _read(), reason, effects));
    await _fire(effects);
  }

  /// [_freeze], for a caller already holding the lock.
  Future<void> _freezeIn(_File file, String reason, _Effects effects) async {
    if (file.frozen != null || file.state == null) return;
    file.frozen = DeviceLogFreeze(reason, _now(), file.state!.head);
    file.joining = false;
    await _write(file);
    effects.changed = true;
  }

  /// Remove a device from the account, signed by this app. It stops being trusted here at once.
  /// Null when done, else why not.
  Future<String?> remove(String pub) async {
    _removing.add(pub);
    try {
      return await _removeOnce(pub);
    } finally {
      _removing.remove(pub);
    }
  }

  Future<String?> _removeOnce(String pub) async {
    final identity = await keys.identity();
    final selfPub = b64e(identity.pub);
    for (var attempt = 0; attempt < _appendAttempts; attempt++) {
      final file = await _read();
      final state = file.state;
      if (state == null) return 'UNAVAILABLE';
      final target = state.active[pub];
      if (target == null) return 'NOT_IN_LOG';
      if (state.active[selfPub] == null) return 'NOT_ACTIVE';
      await _drop(target);
      final entry = await signDevLogEntry(
        nextDevLogEntry(state, op: 'remove', pub: pub, kind: target.kind, machineId: target.machineId,
            label: target.label, signer: selfPub, at: _now()),
        identity,
      );
      final answer = await append(entry);
      if (answer == null) return 'UNAVAILABLE';
      if (answer.error == null) {
        await refresh();
        return null;
      }
      if (answer.error != 'STALE_HEAD') return answer.error;
      await refresh();
      await _sleep(Duration(milliseconds: 200 + _random.nextInt(800) * (attempt + 1)));
    }
    return 'UNAVAILABLE';
  }

  /// Signing out of this app: its key leaves the account's devices (best effort).
  Future<void> leave() async {
    try {
      await remove(await _selfPub());
    } catch (_) {}
  }

  /// What trusting the backend's log again would change; with [confirm], do it. [expectedHead] is the
  /// head the person was shown in the preview: if the backend's log is not that one any more, nothing is
  /// done and the result has [DeviceLogRebaseline.logChanged] set — what gets trusted is what was
  /// reviewed. Another account's list under the sign-in the live log belongs to is refused, preview and
  /// confirm alike ([DeviceLogRebaseline.otherAccount]). Null: the backend's list could not be read or
  /// did not verify.
  Future<DeviceLogRebaseline?> rebaseline({required bool confirm, DevLogHead? expectedHead}) async {
    final entries = <Object?>[];
    var acct = '';
    DevLogHead? head;
    for (var page = 0; page < _joinPages; page++) {
      final got = await fetch(entries.length);
      if (got == null || !_isPosition(got.head.seq)) return null;
      acct = got.acct;
      head = got.head;
      entries.addAll(got.entries);
      if (got.entries.isEmpty || entries.length >= got.head.seq) break;
    }
    final DevLogState next;
    try {
      next = (await applyDevLogEntries(DevLogState.empty(acct), entries)).state;
    } on DevLogError {
      return null;
    }
    if (head == null || next.head != head) return null;
    final effects = _Effects();
    final result = await _locked(() async {
      final file = await _marksIn();
      final same = file.state != null && file.state!.acct == next.acct;
      // Another account's list while the live log is the one of the sign-in this app is under: the
      // backend switched accounts on its own. A review must not move this app there (the account it is
      // signed in to, and every mark on it, would go out of sight): only a sign-in switches accounts.
      // Only a sign-in by hand the list is not stamped with is that switch: none recorded, an adopted one
      // (a session this app took over — whatever stamp the list has, or lacks, from an older version), or
      // the sign-in the list is stamped with is not.
      if (file.state != null && !same) {
        final local = await _localOwner();
        if (local == null || local.startsWith(_adoptedSignIn) || file.owner == local) {
          return const DeviceLogRebaseline.otherAccount();
        }
      }
      if (confirm && expectedHead != null && next.head != expectedHead) return const DeviceLogRebaseline.changed();
      // The list under review is judged against this account's own log as this app verified it: the
      // live file, or — for another account — the one kept when this app left it (its marks go on), or
      // else nothing (every key on it is new here). Never against the account being left.
      final kept = same ? null : await _archivedFileIn(next.acct);
      // Moving from another account's live log: what this app trusted under each goes with it.
      final switching = file.state != null && !same;
      final keptTrust = kept == null ? null : _trustOf((await _archived())[next.acct]);
      final base = same
          ? file
          : kept ?? _File(null, [], null, 0, joinedSeq: 0, preLog: switching ? [] : [...file.preLog]);
      final before = base.state?.active ?? const <String, DevLogMember>{};
      final added = [for (final m in next.active.values) if (before[m.pub] == null) m];
      final removed = [for (final m in before.values) if (next.active[m.pub] == null) m];
      if (confirm) {
        final selfPub = await _selfPub();
        final pre = base.preLog.toSet();
        // Every key the review let in is new here — however the preview and this read differ — unless
        // this app knew it already.
        final news = [
          for (final m in added)
            if (m.pub != selfPub && !pre.contains(m.pub)) m,
        ];
        final toAnnounce = [
          for (final m in news)
            if (!base.announced.contains(m.pub)) m,
        ];
        final parsed = entries.map(DevLogEntry.parse).whereType<DevLogEntry>().toList();
        final departed = _reviewDeparted(base, next, parsed, removed, selfPub, pre);
        // The reviewed list is another account's: the one this app leaves is kept, as on a sign-in (and
        // what a fork suspended in it stays suspended here) — and a kept one of the reviewed account
        // goes on from where it was.
        if (switching) {
          await _archiveIn(file, trust: await keys.trustSnapshot());
          _frozenPeers.clear();
        }
        base
          ..state = next
          ..recent = parsed
          ..frozen = null
          ..notifiedUpTo = next.head.seq
          // The joined point never moves up past the reviewed head: a shorter list (rolled back, or
          // another account's) must leave every key added to it from here on news.
          ..joinedSeq = min(base.joinedSeq ?? base.notifiedUpTo, next.head.seq)
          ..pending = _prune([...base.pending, for (final m in news) m.pub], next)
          ..announced = _prune([...base.announced, for (final m in toAnnounce) m.pub], next)
          // A review lifts what a fork suspended in this list; a kept list's suspensions were never in
          // the preview, so they stay.
          ..suspended = same ? [] : _prune(base.suspended, next)
          ..looseRemoved = []
          ..joining = false
          ..reviewedSeq = next.head.seq
          ..departed = _withDeparted(base.departed, departed)
          ..owner = await _localOwner() ?? base.owner;
        await _carrySuspensionsIn(base);
        // Live first, then out of the archive: a crash in between leaves it in both, never in neither.
        await _write(base);
        if (switching) await keys.writeTrust(keptTrust ?? const {});
        if (kept != null) {
          final all = await _archived();
          if (all.remove(next.acct) != null) await keys.writeDeviceLogArchive(all);
        }
        await _trust(next.active.values.toList());
        for (final m in removed) {
          await _drop(m);
        }
        effects.announce.addAll(toAnnounce);
        effects.changed = true;
      }
      return DeviceLogRebaseline(next.head, added, removed);
    });
    await _fire(effects);
    return result;
  }

  /// What rides this app's side of a `group_sync`.
  Future<Map<String, Object?>?> gossip() async {
    final file = await _read();
    final state = file.state;
    // Not this sign-in's log yet (it may be the account this app just left): nothing to say.
    if (state == null || !await _ownsFile(file)) return null;
    // The newest hashes let a peer that finds the logs forked say where they split.
    final from = max(0, state.hashes.length - _gossipHashes);
    return {
      'acct': state.acct,
      'head': state.head.toJson(),
      'frozen': file.frozen != null,
      'hashes': [
        for (var i = from; i < state.hashes.length; i++) {'seq': i + 1, 'hash': state.hashes[i]},
      ],
    };
  }

  /// A machine's answer to this app's `group_sync`: its head, whether it is frozen, and the entries
  /// this app lacks if it is behind.
  Future<void> heard(String machinePub, Object? raw) async {
    final file = await _marks();
    final state = file.state;
    if (state == null || raw is! Map) return;
    // A sign-in waiting for its first read: the file may be the account left behind, and a machine of
    // the new one would freeze it as a fork. Nothing is judged until the log is this sign-in's.
    if (!await _ownsFile(file)) return;
    // Another account's log (a machine still signed in to it): nothing in it says anything about this
    // one. A machine too old to say which account is heard as before.
    if (raw['acct'] != null && raw['acct'] != state.acct) return;
    _frozenPeers[machinePub] = raw['frozen'] == true;
    final theirs = DevLogHead.fromJson(raw['head']);
    if (theirs == null) return;
    final relation = compareDevLogHead(state, theirs);
    if (relation == 'fork') {
      await _freeze('fork');
      return _suspendAfterFork(raw);
    }
    if (relation == 'behind') {
      final tail = raw['tail'];
      final missing = tail is List
          ? [for (final e in tail) if ((DevLogEntry.parse(e)?.seq ?? 0) > state.head.seq) e]
          : const <Object?>[];
      // A tail that does not continue this log is a fork; and a log already frozen on one can still
      // learn from this machine's hashes where it split.
      if (file.frozen != null || (missing.isNotEmpty && !await _acceptFromPeer(missing))) {
        await _suspendAfterFork(raw);
      }
      unawaited(refresh());
    }
  }

  /// A fork a peer proved with its hashes: the keys added at or after the split — and new here — are
  /// not trusted until the list is reviewed ([rebaseline]). Only locally: nothing is tombstoned or
  /// written to the log. Without usable hashes the freeze alone stands.
  Future<void> _suspendAfterFork(Object? theirs) async {
    final changed = await _locked(() async {
      final file = await _read();
      final state = file.state;
      if (state == null || file.frozen?.reason != 'fork') return false;
      final split = devLogDivergence(state, theirs);
      if (split == null) return false;
      final selfPub = await _selfPub();
      // Only keys nobody here has marked as seen — and not one a review (`rebaseline`) already let in:
      // another device's old branch must not cost this one the devices its user just looked at.
      final reviewed = file.reviewedSeq ?? -1;
      final fresh = [
        for (final m in state.active.values)
          if (m.seq >= split &&
              m.pub != selfPub &&
              file.pending.contains(m.pub) &&
              m.seq > reviewed &&
              !file.suspended.contains(m.pub))
            m,
      ];
      if (fresh.isEmpty) return false;
      file.suspended = [...file.suspended, for (final m in fresh) m.pub];
      await _write(file);
      for (final m in fresh) {
        if (m.kind != 'machine') continue;
        final current = await keys.peer(m.machineId);
        if (current != null && b64e(current.pub) == m.pub) await keys.unlink(m.machineId);
      }
      return true;
    });
    if (changed) onChanged?.call();
  }

  /// Keys not trusted here after a fork, until [rebaseline] — and every key a fork suspended in another
  /// account's kept log, which no other account's log can bring back in.
  Future<Set<String>> suspendedPubs() async => {...(await _read()).suspended, ...await _archivedSuspended()};

  /// Mark new devices as seen: the ones in [pubs] (what a window displayed), one ([pub]), or every one
  /// (neither). The "already on your account" list is [seeBaseline]. Persisted, so it holds across
  /// restarts. A key a fork suspended stays flagged when it is only part of a list that was looked at;
  /// [pub] — "It's mine" on that very device — is the person vouching for it, and lifts its suspension
  /// (here and in every kept account's log). A key that joined and left before anyone looked
  /// ([DeviceLogListing.departed]) is cleared the same way: named, or every one.
  ///
  /// [confirm] — "It's mine", pressed for ONE device ([pub], or [pubs] naming only it) — also tells the
  /// account's other devices, with an acknowledgement this app signs (device_ack.dart): they stop showing
  /// it as New too. Never for a list that was only looked at, or every device at once: only an explicit
  /// "It's mine" vouches. Marking it seen here is done first; the result says whether the other devices
  /// were told (false: the backend did not take it, or there was nothing to tell).
  Future<bool> dismiss({String? pub, List<String>? pubs, bool confirm = false}) async {
    final one = pub ?? (pubs != null && pubs.length == 1 ? pubs.first : null);
    var share = false;
    final lifted = <DevLogMember>[];
    final changed = await _locked(() async {
      final file = await _marksIn();
      if (file.state == null) return false;
      final wasNew = one != null && file.pending.contains(one);
      final named = pub != null || pubs != null;
      final gone = {...?pubs, ?pub};
      file.pending = [
        for (final k in file.pending)
          if ((named ? !gone.contains(k) : false) || (file.suspended.contains(k) && k != pub)) k,
      ];
      file.departed = [
        for (final d in file.departed)
          if (named && !gone.contains(d.pub)) d,
      ];
      final lifting = pub != null && file.suspended.contains(pub) ? pub : null;
      if (lifting != null) {
        file.suspended = [for (final k in file.suspended) if (k != lifting) k];
        final m = file.state!.active[lifting];
        if (m != null) lifted.add(m);
      }
      await _write(file);
      if (lifting != null) await _unsuspendArchivedIn([lifting]);
      if (lifted.isNotEmpty) await _trust(lifted);
      // Only a key that was new here, and that this app trusts now: one a fork suspended here (and
      // "It's mine" did not lift) is not this app's to vouch for.
      share = confirm && wasNew && !(await suspendedPubs()).contains(one);
      return true;
    });
    if (changed) onChanged?.call();
    return share ? _shareAck(one!) : false;
  }

  /// Sign "It's mine" for [pub] and hand it to the backend for the account's other devices. Only from a
  /// log this app verified, is on, and that is not frozen (a frozen list is not one to vouch from), about
  /// a key on it that is not this app. Never throws.
  Future<bool> _shareAck(String pub) async {
    final post = postAck;
    if (post == null) return false;
    try {
      final file = await _read();
      final state = file.state;
      final identity = await keys.identity();
      final selfPub = b64e(identity.pub);
      if (state == null || file.frozen != null || !await _ownsFile(file)) return false;
      if (pub == selfPub || state.active[selfPub] == null) return false;
      final member = state.active[pub];
      if (member == null) return false;
      final ack = await signDevAck(
        DevAck(v: devAckVersion, acct: state.acct, pub: pub, addSeq: member.seq, signer: selfPub, at: _now()),
        identity,
      );
      return await post(ack);
    } catch (_) {
      return false;
    }
  }

  /// The "Already on your account" list was acknowledged: the first read is over, whatever comes after
  /// is news — or a backend that stalls that read could add a key to a list nobody looks at again.
  Future<void> seeBaseline() => _change((file) {
    file
      ..baselineSeen = true
      ..joining = false;
  });

  /// Read the file, [edit] it and write it back, under the lock; nothing when there is no log yet.
  Future<void> _change(void Function(_File file) edit) async {
    final changed = await _locked(() async {
      final file = await _marksIn();
      if (file.state == null) return false;
      edit(file);
      await _write(file);
      return true;
    });
    if (changed) onChanged?.call();
  }

  /// Every add and remove in the log, newest first, as this app verified it: the entries come from the
  /// backend but each must hash to what this app already verified, or the log freezes. Offline, what
  /// is kept locally (`complete: false`).
  Future<DeviceLogHistory> history() => _historying ??= _historyOnce().whenComplete(() => _historying = null);

  /// One walk at a time: two interleaved on the same cache would each read the other's entries as a
  /// gap in the log and freeze it.
  Future<DeviceLogHistory>? _historying;

  Future<DeviceLogHistory> _historyOnce() async {
    await refresh();
    final file = await _marks();
    final state = file.state;
    if (state == null) return const DeviceLogHistory(rows: [], complete: false);
    if (_histAcct != state.acct) {
      _histAcct = state.acct;
      _histCache = [];
    }
    final last = _histCache.isEmpty ? null : _histCache.last;
    if (last != null && (last.seq > state.head.seq || devLogHash(last) != state.hashes[last.seq - 1])) {
      _histCache = [];
    }
    for (var page = 0; page < _pages && _histCache.length < state.head.seq; page++) {
      final since = _histCache.length;
      final got = await fetch(since);
      if (got == null || got.acct != state.acct) break;
      var progressed = false;
      for (final raw in got.entries) {
        final e = DevLogEntry.parse(raw);
        final rawSeq = raw is Map ? raw['seq'] : null;
        final seq = e?.seq ?? (rawSeq is int ? rawSeq : 0);
        if (seq <= _histCache.length || seq > state.head.seq) continue;
        // At a position this app verified, anything unreadable or off-hash means the backend is lying
        // about the past: freeze, and show only what was already checked.
        if (e == null || e.seq != _histCache.length + 1 || devLogHash(e) != state.hashes[e.seq - 1]) {
          // Only against the log this walk started from: if the file was rebaselined (or moved to
          // another account) while the pages were on their way, the mismatch is with a log that is
          // gone, and says nothing about the backend.
          final now = (await _read()).state;
          if (now == null || now.acct != state.acct || now.head != state.head) {
            _histCache = [];
            _histAcct = null;
            return _historyOf(const [], false);
          }
          await _freeze('fork');
          return _historyOf(_histCache, false);
        }
        _histCache.add(e);
        progressed = true;
      }
      if (!progressed) break;
    }
    return _historyOf(_histCache, _histCache.length >= state.head.seq);
  }

  Future<DeviceLogHistory> _historyOf(List<DevLogEntry> fetched, bool complete) async {
    final file = await _read();
    final state = file.state;
    if (state == null) return const DeviceLogHistory(rows: [], complete: false);
    // Offline, the newest entries kept locally fill in what could not be fetched.
    final from = fetched.isEmpty ? 0 : fetched.last.seq;
    final entries = complete ? fetched : [...fetched, for (final e in file.recent) if (e.seq > from) e];
    return DeviceLogHistory(
      rows: devLogHistory(
        entries,
        selfPub: await _selfPub(),
        joinedSeq: file.joinedSeq,
        // A key that joined and left before anyone looked is still new, in its rows too.
        pending: [...file.pending, for (final d in file.departed) d.pub],
        active: state.active,
        loose: file.looseRemoved,
      ),
      complete: complete,
    );
  }

  /// The account's devices as this app's log has them.
  Future<DeviceLogListing> list() async {
    final file = await _marks();
    final selfPub = await _selfPub();
    final members = (file.state?.active.values.toList() ?? [])..sort((a, b) => a.seq.compareTo(b.seq));
    final labels = {for (final m in members) m.pub: m.label};
    final joinedSeq = file.joinedSeq ?? 0;
    final pre = file.preLog.toSet();
    return DeviceLogListing(
      members: [
        for (final m in members)
          DeviceLogRow(
            m,
            fingerprint: fingerprint(b64d(m.pub)),
            self: m.pub == selfPub,
            pending: file.pending.contains(m.pub),
            suspended: file.suspended.contains(m.pub),
            confirmed: file.confirmed[m.pub],
          ),
      ],
      frozen: file.frozen,
      frozenPeers: [
        for (final e in _frozenPeers.entries)
          if (e.value) labels[e.key] ?? fingerprint(b64d(e.key)),
      ],
      pending: file.pending,
      suspended: file.suspended,
      joinedSeq: joinedSeq,
      baseline: [
        for (final m in members)
          if (m.pub != selfPub && (m.seq <= joinedSeq || pre.contains(m.pub))) m.pub,
      ],
      baselineSeen: file.baselineSeen,
      departed: file.departed,
      registerError: _registerError,
    );
  }
}

/// Whether [seq] can be a log position: a whole number, not negative, not past what a double holds.
bool _isPosition(int seq) => seq >= 0 && seq <= 9007199254740991;

String _clip(String label) {
  final clean = label.replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ').trim();
  return clean.length > devLogLabelMax ? clean.substring(0, devLogLabelMax) : clean;
}