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.

29.1 KB
Raw Blame
/// The window's half of the zoo. An account's zoo lives on the server and is
/// reached the way the desk is: `GET /api/zoo` and `POST /api/zoo/ops` through
/// the local harnessd (its Unix socket, or loopback TCP), refreshed on the
/// `zoo_changed` local frame. A guest keeps a local zoo with the same shape and
/// rules, drawn here, and it is sent once with `zoo.seed` on first sign-in.
///
/// Nothing is shown until the zoo has loaded: [loaded] stays false while the
/// scope is unknown (a signed-in window before its profile arrives) and while
/// the first read is in flight, so a boot never flashes a stranger's nest.
///
/// Daemons ship dark (daemons/README.md, "Off switches"). A signed-in window
/// shows them only once `GET /api/zoo` answers 200; a 404 (or a 401, or no way
/// to ask) is [DaemonsSwitch.off]: nothing is shown, read, kept or sent, and
/// the window behaves exactly as it did before daemons existed. A failed read
/// is not an answer: whatever was known stands, and it is asked again. A
/// guest's durable local zoo stays off. Settings → Experimental opens the
/// account collection. The window-only preview is reserved for render fixtures.
library;

import 'dart:async';
import 'dart:convert';
import 'dart:math';

import 'package:flutter/foundation.dart';

import '../api/api_client.dart';
import '../core/local_key_value_store.dart';
import 'individuals.dart';
import 'render.dart' show habitProgress;
import 'roster.dart';
import 'zoo.dart';
import 'zoo.dart' as zoo_rules show eggsBeingEarned, nearestEgg;

abstract interface class ZooTransport {
  /// `{revision, zoo}`, or null when daemons are off: a 404 (switched off on
  /// the server or in harnessd, or a harnessd that predates the zoo) or a
  /// 401. A failure to answer throws: that is not off.
  Future<Map<String, dynamic>?> fetch();

  /// `{revision, zoo, hatched}`, or null under the same conditions.
  Future<Map<String, dynamic>?> apply(List<Map<String, dynamic>> ops);
}

class ApiZooTransport implements ZooTransport {
  ApiZooTransport(this.api);
  final ApiClient api;
  @override
  Future<Map<String, dynamic>?> fetch() => api.zoo();
  @override
  Future<Map<String, dynamic>?> apply(List<Map<String, dynamic>> ops) =>
      api.zooOps(ops);
}

/// Something that arrived in the zoo since it was last shown: learned from
/// this window's own answers and from other windows' changes alike, by
/// comparing what the zoo was with what it is (a first read and a seed are
/// baselines, never news).
sealed class ZooEvent {
  const ZooEvent();
}

/// A new egg in the nest: earned from work, a first or easter egg, or one
/// that was held until there was room.
class ZooEggArrived extends ZooEvent {
  const ZooEggArrived(this.egg);
  final ZooEgg egg;
}

/// An individual's bond reached a new level (and maybe a new version).
class ZooDaemonGrew extends ZooEvent {
  const ZooDaemonGrew(this.daemon, {required this.versionChanged});
  final ZooDaemon daemon;
  final bool versionChanged;
}

/// A fresh hatch after the initial collection read.
class ZooDaemonHatched extends ZooEvent {
  const ZooDaemonHatched(this.daemon);
  final ZooDaemon daemon;
}

/// Whether this window has daemons at all.
enum DaemonsSwitch {
  /// Not decided yet: no profile, or the first read has no answer. Nothing
  /// shows and nothing is sent; no space is kept for the slot.
  unknown,

  /// The server has no zoo for this account (404), harnessd is switched off
  /// (`DAEMONS_OFF`), or the account has not opted in. Everything daemon-related
  /// stays hidden and silent.
  off,

  /// `GET /api/zoo` answered 200, or a test fixture enabled a local collection.
  on,
}

enum ZooSource {
  /// Not loaded yet, or no scope.
  none,

  /// The account's zoo on the server.
  account,

  /// This installation's local zoo: a guest, or a harnessd without a zoo.
  local,

  /// A window-only test collection. Never stored, seeded or sent to an account.
  preview,
}

class ZooController extends ChangeNotifier {
  ZooController({
    this.storage,
    DaemonRoster? roster,
    Random? random,
    DateTime Function()? now,
  }) : roster = roster ?? daemonRoster,
       _random = random ?? Random.secure(),
       _now = now ?? DateTime.now;

  static const localZooKey = 'daemons.zoo.v1.local';

  /// Daemons are asked about again once the last answer is this old (on or
  /// off), besides on `zoo_changed` and a reconnect; a failed read is retried
  /// no less often than this.
  static const recheckEvery = Duration(hours: 6);
  static String prefsKey(String scope) =>
      'daemons.prefs.v1.${base64Url.encode(utf8.encode(scope))}';

  final LocalKeyValueStore? storage;
  final DaemonRoster roster;
  final Random _random;
  final DateTime Function() _now;

  String? _scope;
  ZooTransport? _remote;
  bool _enabled = true;
  bool _off = false;
  bool _prefsRead = false;
  DateTime? _answeredAt;
  bool _fetching = false;
  ZooSource _source = ZooSource.none;
  Zoo _zoo = Zoo.empty;
  int _revision = 0;
  int _generation = 0;
  bool _disposed = false;
  bool _seeded = false;
  Zoo _local = Zoo.empty;
  Zoo? _previewZoo;
  static const _previewScope = 'preview';
  final _days = <String>{};
  final _easterAsked = <String>{};
  bool _hintSeen = false;
  String? _hatchingEgg;
  Future<void> _queue = Future.value();
  Future<void> _saving = Future.value();
  final _events = StreamController<ZooEvent>.broadcast(sync: true);
  final _unsent = <Map<String, dynamic>>[];
  Timer? _retry;
  int _failures = 0;

  String? get scope => _scope;
  ZooSource get source => _source;

  /// Whether this window has daemons: [DaemonsSwitch.on] exactly when the zoo
  /// has [loaded].
  DaemonsSwitch get daemons => loaded
      ? DaemonsSwitch.on
      : _off
      ? DaemonsSwitch.off
      : DaemonsSwitch.unknown;

  /// New eggs and level-ups, for the face and the notices.
  Stream<ZooEvent> get events => _events.stream;
  bool get loaded => _source != ZooSource.none;
  bool get isAccount => _source == ZooSource.account;
  bool get isPreview => _scope == _previewScope;
  Zoo get zoo => _zoo;
  int get revision => _revision;
  String? get hatchingEgg => _hatchingEgg;
  int get habitsDone => _zoo.habits.length;
  int get habitsNeeded => roster.rules.firstEggNeed;

  /// Habits that count toward the first egg now (render.mjs
  /// `habitProgress`): up to [habitsNeeded], and one short of it until every
  /// required habit (a finished turn) is among them.
  int get habitsCounted => habitProgress(roster, _zoo.habits).$1;

  /// The habits the first egg cannot come without, still to do.
  List<DaemonHabit> get habitsRequiredLeft => [
    for (final h in roster.rules.habits)
      if (roster.rules.firstEggRequire.contains(h.key) &&
          !_zoo.habits.contains(h.key))
        h,
  ];

  /// The first egg's rule in words, from the roster: `finish a turn in a
  /// harness, and any 2 more`.
  String get firstEggRule {
    final rules = roster.rules;
    final required = [
      for (final h in rules.habits)
        if (rules.firstEggRequire.contains(h.key)) _lower(h.label),
    ];
    final more = rules.firstEggNeed - required.length;
    if (required.isEmpty) return 'any ${rules.firstEggNeed}';
    return '${required.join(', ')}${more > 0 ? ', and any $more more' : ''}';
  }

  /// Habits done toward the setup egg (the second habit egg), and how many
  /// it takes; null once it has come or when the roster has none.
  (int, int)? get setupProgress {
    if (roster.rules.setupEggNeed == null || _zoo.setupEgg) return null;
    return habitProgress(roster, _zoo.habits, kind: 'setup');
  }

  /// Every egg being earned now, each at its stage (README, "Eggs").
  List<ZooEggProgress> get eggsBeingEarned =>
      zoo_rules.eggsBeingEarned(roster, _zoo, now: _now());

  /// The egg nearest to hatching: a waiting one (`p4`), else the one being
  /// earned furthest along. What the status line shows as an egg.
  ZooEggProgress? get nearestEgg =>
      zoo_rules.nearestEgg(roster, _zoo, now: _now());

  static String _lower(String label) =>
      label.isEmpty ? label : '${label[0].toLowerCase()}${label.substring(1)}';

  /// The individual in the status line, with its species' roster entry.
  ZooDaemon? get paired => _zoo.paired;
  DaemonDef? get pairedDef => roster.byId(paired?.id);

  /// An individual's traits, rolled once per species and seed.
  DaemonTraits? traitsOf(ZooDaemon? daemon) {
    if (daemon == null) return null;
    return _traits['${daemon.id} ${daemon.seed}'] ??= rollTraits(
      roster,
      daemon.id,
      daemon.seed,
    );
  }

  final _traits = <String, DaemonTraits?>{};

  /// The first egg waiting to be hatched.
  ZooEgg? get readyEgg => _zoo.eggs.firstOrNull;

  bool get needsHint => loaded && _zoo.daemons.isEmpty && !_hintSeen;

  /// Choose whose zoo this window shows: `guest`, `account:<id>`, or null
  /// while that is not known yet. A new scope forgets everything. An account
  /// is asked through [remote] (none: off); a guest's local zoo shows only
  /// when [enabled] and is otherwise off
  /// without reading anything.
  void bind(String? scope, {ZooTransport? remote, bool enabled = true}) {
    if (_disposed ||
        (scope == _scope && remote == _remote && enabled == _enabled)) {
      return;
    }
    _scope = scope;
    _remote = remote;
    _enabled = enabled;
    _source = ZooSource.none;
    _zoo = Zoo.empty;
    _local = Zoo.empty;
    _prefsRead = false;
    _off = false;
    _revision = 0;
    _hatchingEgg = null;
    _unsent.clear();
    _retry?.cancel();
    _retry = null;
    _answeredAt = null;
    _fetching = false;
    _failures = 0;
    _days.clear();
    _easterAsked.clear();
    _hintSeen = false;
    final generation = ++_generation;
    if (scope != null &&
        (!enabled || (remote == null && scope != 'guest' && !isPreview))) {
      // Nothing to ask, nothing to read: off from the start.
      _off = true;
    }
    notifyListeners();
    if (scope != null && !_off) unawaited(_load(generation));
  }

  /// A render fixture can preview a creature with the server feature off.
  /// Keep its collection in this controller only, across hide/show, and never
  /// use the guest's persisted zoo (which can later be seeded to an account).
  void showPreview() => bind(_previewScope);

  /// Daemons are off: `DAEMONS_OFF` from harnessd, or a 404 on a write. All
  /// of it goes, at once; an account is asked again later ([recheckIfDue],
  /// `zoo_changed`, a reconnect).
  void switchOff() {
    if (_disposed || _scope == null || _off) return;
    _goOff(_generation);
  }

  void _goOff(int generation) {
    final was = loaded;
    _off = true;
    _source = ZooSource.none;
    _zoo = Zoo.empty;
    _revision = 0;
    _hatchingEgg = null;
    _unsent.clear();
    _retry?.cancel();
    _retry = null;
    _failures = 0;
    _answeredAt = _now();
    if (was) debugPrint('zoo: daemons are off');
    notifyListeners();
  }

  /// Ask again when the last answer is [recheckEvery] old: no timer is kept
  /// for it; the window calls this as it syncs.
  void recheckIfDue() {
    final at = _answeredAt;
    if (_disposed ||
        _scope == null ||
        _remote == null ||
        _fetching ||
        at == null ||
        _now().difference(at) < recheckEvery) {
      return;
    }
    unawaited(_fetch(_generation));
  }

  bool _current(int generation) => !_disposed && generation == _generation;

  Future<void> _load(int generation) async {
    if (isPreview) {
      _source = ZooSource.preview;
      _hintSeen = true;
      // Start with the same unhatched egg as a new collection. The preview
      // earns its first hatch through habits; it never preselects a creature.
      _show(_previewZoo ??= Zoo.empty, baseline: true);
      return;
    }
    if (_remote == null) {
      // The durable guest zoo, retained for compatibility and test fixtures.
      await _readPrefs();
      if (!_current(generation)) return;
      _adoptLocal();
      return;
    }
    await _fetch(generation);
  }

  /// This installation's local zoo and this scope's preferences, read once,
  /// and only once daemons are on.
  Future<void> _readPrefs() async {
    if (_prefsRead) return;
    final scope = _scope!;
    final generation = _generation;
    await _saving;
    final local = await _readJson(localZooKey);
    final prefs = await _readJson(prefsKey(scope));
    if (!_current(generation) || _prefsRead) return;
    _prefsRead = true;
    _local = Zoo.fromJson(local?['zoo'], roster);
    _seeded = local?['seeded'] == true;
    for (final day in prefs?['days'] as List? ?? const []) {
      if (day is String) _days.add(day);
    }
    _hintSeen = prefs?['hintSeen'] == true;
  }

  void _adoptLocal() {
    _source = ZooSource.local;
    _revision = 0;
    _show(_local, baseline: true);
  }

  /// Show [next]. Unless it is a baseline (a first read, a seed), whatever
  /// arrived since the zoo was last shown is told to [events].
  void _show(Zoo next, {bool baseline = false}) {
    final before = _zoo;
    _zoo = next;
    notifyListeners();
    if (baseline || _disposed) return;
    for (final egg in next.eggs) {
      if (!before.eggs.any((e) => e.id == egg.id)) {
        _events.add(ZooEggArrived(egg));
      }
    }
    for (final daemon in next.daemons) {
      final was = before.byUid(daemon.uid);
      final age = _now().difference(daemon.hatchedDate);
      if (was == null &&
          !age.isNegative &&
          age <= const Duration(seconds: 15)) {
        _events.add(ZooDaemonHatched(daemon));
      }
      if (was != null &&
          (daemon.bond > was.bond ||
              roster.versionIndex(daemon.version) >
                  roster.versionIndex(was.version))) {
        _events.add(
          ZooDaemonGrew(daemon, versionChanged: daemon.version != was.version),
        );
      }
    }
  }

  Future<void> _fetch(int generation) async {
    final remote = _remote;
    if (remote == null || !_enabled || !_current(generation)) return;
    Map<String, dynamic>? raw;
    _fetching = true;
    try {
      raw = await remote.fetch();
    } catch (error) {
      if (_current(generation)) _fetching = false;
      if (!_current(generation)) return;
      // Not an answer: whatever was known stands (on stays on, off stays
      // off), and it is asked again.
      debugPrint('zoo: read failed: $error');
      if (!loaded) _scheduleRetry(generation);
      return;
    }
    if (!_current(generation)) return;
    _fetching = false;
    if (raw == null) {
      // 404 (the server's zoo is switched off, or harnessd's is) or 401:
      // daemons are off. Nothing shows, nothing is sent.
      _goOff(generation);
      return;
    }
    await _readPrefs();
    if (!_current(generation)) return;
    _off = false;
    _answeredAt = _now();
    final wasAccount = isAccount;
    if (!wasAccount) {
      // At sign-in the guest's zoo goes first, ahead of any habit this window
      // is about to report: the server refuses a seed once the account holds
      // any daemon, egg or habit.
      if (!_seeded &&
          !_local.isEmpty &&
          !Zoo.fromJson(raw['zoo'], roster).holdsAnything) {
        _enqueueSeed(generation);
      }
      _failures = 0;
    }
    _adopt(raw, force: !wasAccount, baseline: !wasAccount);
    if (!wasAccount && _unsent.isNotEmpty) _flushUnsent(generation);
  }

  /// A failed read is asked again after 5 s, doubling up to [recheckEvery];
  /// a failed write (daemons on) after 5 s, doubling up to a minute.
  void _scheduleRetry(int generation) {
    _failures++;
    final seconds = 5 * (1 << (_failures - 1).clamp(0, 12));
    final wait = Duration(
      seconds: loaded
          ? seconds.clamp(5, 60)
          : min(seconds, recheckEvery.inSeconds),
    );
    _retry?.cancel();
    _retry = Timer(wait, () {
      if (!_current(generation)) return;
      if (!loaded) {
        unawaited(_fetch(generation));
      } else {
        _flushUnsent(generation);
      }
    });
  }

  /// Take the server's answer when it is not older than what is shown.
  bool _adopt(
    Map<String, dynamic> raw, {
    bool force = false,
    bool baseline = false,
  }) {
    final revision = raw['revision'];
    if (revision is! int) return false;
    if (!force && isAccount && revision < _revision) return false;
    _source = ZooSource.account;
    _revision = revision;
    _show(_overlayUnsent(Zoo.fromJson(raw['zoo'], roster)), baseline: baseline);
    return true;
  }

  /// This window's unacknowledged ops laid back over the server's answer, so a
  /// reply to an earlier batch does not briefly undo a later one. Eggs are
  /// never granted here: that is the server's decision.
  Zoo _overlayUnsent(Zoo zoo) {
    var next = zoo;
    for (final op in _unsent) {
      switch (op['op']) {
        case 'zoo.habit':
          final key = op['key'] as String;
          if (!next.habits.contains(key)) {
            next = next.copyWith(habits: [...next.habits, key]);
          }
        case 'zoo.pair':
          if (next.byUid(op['uid'] as String?) != null) {
            next = next.copyWith(pair: op['uid'] as String);
          }
        case 'zoo.nickname' || 'zoo.autonomy' || 'zoo.consent':
          next = applyZooOps(
            roster,
            next,
            [op],
            random: _random,
            now: _now(),
          ).zoo;
      }
    }
    return next;
  }

  /// A guest's zoo goes to the account once, first in the queue. The server
  /// applies it only while the account holds no daemon, egg or habit; its
  /// answer is a baseline (the guest's eggs come back under server ids).
  void _enqueueSeed(int generation) {
    final seed = _local.toJson();
    _enqueue(() async {
      if (!_current(generation) || _seeded) return;
      try {
        final answer = await _remote!.apply([
          {'op': 'zoo.seed', 'zoo': seed},
        ]);
        if (!_current(generation)) return;
        if (answer == null) {
          _goOff(generation);
          return;
        }
        _seeded = true;
        _saveLocal();
        _adopt(answer, baseline: true);
      } catch (error) {
        debugPrint('zoo: seed failed: $error');
      }
    });
  }

  /// `zoo_changed { revision }`: fetch only when the push is news.
  void pushed(int? revision) {
    if (_disposed || _scope == null || _remote == null) return;
    if (isAccount && revision != null && revision <= _revision) return;
    unawaited(_fetch(_generation));
  }

  /// Read again, e.g. when harnessd's backend link comes back.
  void refresh() {
    if (_disposed || _scope == null || _remote == null) return;
    unawaited(_fetch(_generation));
  }

  // ── ops ────────────────────────────────────────────────────────────────────

  /// Record a first-egg habit. Sent once; the server grants the egg.
  void habit(String key) {
    if (!loaded ||
        _zoo.habits.contains(key) ||
        !roster.rules.habits.any((h) => h.key == key)) {
      return;
    }
    final op = {'op': 'zoo.habit', 'key': key};
    if (!isAccount) {
      _applyLocal([op]);
      return;
    }
    // Optimistic for the habit only: the egg is the server's to grant.
    _show(_zoo.copyWith(habits: [..._zoo.habits, key]));
    _sendLater(op);
  }

  /// Pair the individual [uid] (`zoo.pair { uid }`).
  void pair(String uid) {
    final daemon = _zoo.byUid(uid);
    if (!loaded || daemon == null || _zoo.pair == uid) return;
    final op = {'op': 'zoo.pair', 'uid': uid};
    if (!isAccount) {
      _applyLocal([op]);
      return;
    }
    _show(_zoo.copyWith(pair: uid));
    _sendLater(op);
  }

  /// Turn the pair's autonomy dial (`zoo.autonomy`). A guest's is kept in
  /// its local zoo, and the brain hears it in `daemon_presence`.
  void autonomy(String level) {
    if (!loaded || !isZooAutonomy(level) || _zoo.autonomy == level) return;
    final op = {'op': 'zoo.autonomy', 'level': level};
    if (!isAccount) {
      _applyLocal([op]);
      return;
    }
    _show(_zoo.copyWith(autonomy: level));
    _sendLater(op);
  }

  /// The first-day answer (`zoo.consent`): whether the daemon may watch at
  /// all. Yes starts the dial at `watch`; `suggest` is a second, separate
  /// step. A guest's is kept locally and heard in `daemon_presence`.
  void consent({required bool watching}) {
    if (!loaded || _zoo.consent?.watching == watching) return;
    final op = {'op': 'zoo.consent', 'watching': watching};
    if (!isAccount) {
      _applyLocal([op]);
      return;
    }
    _show(applyZooOps(roster, _zoo, [op], random: _random, now: _now()).zoo);
    _sendLater(op);
  }

  /// Name the individual [uid] (`zoo.nickname { uid, name }`: 1-24
  /// printable characters, trimmed), or clear it with null. Answers false for
  /// a name the rules refuse.
  bool nickname(String uid, String? name) {
    final daemon = _zoo.byUid(uid);
    if (!loaded || daemon == null) return false;
    final value = name?.trim();
    if (value != null && value.isNotEmpty && !validNickname(value)) {
      return false;
    }
    final named = value == null || value.isEmpty ? null : value;
    final op = {'op': 'zoo.nickname', 'uid': uid, 'name': named};
    if (!isAccount) {
      _applyLocal([op]);
      return true;
    }
    _show(applyZooOps(roster, _zoo, [op], random: _random, now: _now()).zoo);
    _sendLater(op);
    return true;
  }

  /// Whether [word] is one of the roster's easter words (by its hash: the
  /// words themselves never ship).
  bool isEasterWord(String word) {
    final w = word.trim().toLowerCase();
    return w.isNotEmpty &&
        w.length <= 64 &&
        roster.rules.easterHashes.contains(easterHash(w));
  }

  /// An easter word typed (`xyzzy` in Cmd-O). Sent once: a word already
  /// used, or already asked for from this window, is not sent again.
  bool easter(String word) {
    final w = word.trim().toLowerCase();
    if (!loaded || !isEasterWord(w)) return false;
    final hash = easterHash(w);
    if (_zoo.easter.contains(hash) || !_easterAsked.add(hash)) return false;
    word = w;
    final op = {'op': 'zoo.easter', 'word': word};
    if (!isAccount) {
      _applyLocal([op]);
      return true;
    }
    _sendLater(op);
    return true;
  }

  /// Open an egg. The draw happens on the server for an account (here only
  /// for a local zoo); null when the egg is gone or harnessd cannot be reached.
  Future<ZooHatch?> hatch(String eggId) async {
    if (!loaded || _hatchingEgg != null) return null;
    if (!_zoo.eggs.any((e) => e.id == eggId)) return null;
    _hatchingEgg = eggId;
    notifyListeners();
    final generation = _generation;
    try {
      final op = {'op': 'zoo.hatch', 'eggId': eggId};
      if (!isAccount) {
        return _applyLocal([op]).where((h) => h.eggId == eggId).firstOrNull;
      }
      final completer = Completer<Map<String, dynamic>?>();
      _enqueue(() async {
        try {
          completer.complete(await _remote!.apply([op]));
        } catch (error) {
          completer.completeError(error);
        }
      });
      final answer = await completer.future;
      if (!_current(generation)) return null;
      if (answer == null) {
        _goOff(generation);
        return null;
      }
      final before = _zoo;
      _adopt(answer);
      final hatch = [
        for (final h in answer['hatched'] as List? ?? const [])
          ?ZooHatch.fromJson(h),
      ].where((h) => h.eggId == eggId).firstOrNull;
      return hatch == null ? null : _withIndividual(hatch, before);
    } catch (error) {
      debugPrint('zoo: hatch failed: $error');
      return null;
    } finally {
      if (_current(generation)) {
        _hatchingEgg = null;
        notifyListeners();
      }
    }
  }

  /// A hatch answered without the new individual's uid or seed (a server
  /// from before individuals): the individual of its species that was not
  /// there before, else the species' first.
  ZooHatch _withIndividual(ZooHatch hatch, Zoo before) {
    final own = _zoo.byUid(hatch.uid);
    if (own != null) {
      return hatch.uid != null && hatch.seed == own.seed
          ? hatch
          : ZooHatch(
              eggId: hatch.eggId,
              daemonId: hatch.daemonId,
              uid: own.uid,
              seed: own.seed,
              shiny: hatch.shiny,
              duplicate: hatch.duplicate,
              xp: hatch.xp,
              serial: hatch.serial ?? own.serial,
            );
    }
    final species = _zoo.ofSpecies(hatch.daemonId);
    final found =
        species.where((d) => before.byUid(d.uid) == null).lastOrNull ??
        species.firstOrNull;
    if (found == null) return hatch;
    return ZooHatch(
      eggId: hatch.eggId,
      daemonId: hatch.daemonId,
      uid: found.uid,
      seed: found.seed,
      shiny: hatch.shiny,
      duplicate: hatch.duplicate,
      xp: hatch.xp,
      serial: hatch.serial ?? found.serial,
    );
  }

  List<ZooHatch> _applyLocal(List<Map<String, dynamic>> ops) {
    final result = applyZooOps(roster, _zoo, ops, random: _random, now: _now());
    if (isPreview) {
      _previewZoo = result.zoo;
    } else {
      _local = result.zoo;
      _saveLocal();
    }
    _show(result.zoo);
    return result.hatched;
  }

  static final _unsafe = RegExp(r'[^A-Za-z0-9_-]');

  /// A guest's finished turns, counted here with the server's rules
  /// (`zoo.turn`: the daily cap, earned eggs, the pair's xp), [away] of them
  /// finished while the person was away. Never for an account zoo: harnessd
  /// reports those turns, and they would count twice. A preview counts them
  /// only in memory, even while its window is signed in.
  void recordTurns(int n, {required String machineId, int away = 0}) {
    if (!loaded || isAccount || (_scope != 'guest' && !isPreview) || n <= 0) {
      return;
    }
    final now = _now();
    var machine = machineId.replaceAll(_unsafe, '-');
    if (machine.isEmpty) machine = 'local';
    if (machine.length > 64) machine = machine.substring(0, 64);
    final ops = <Map<String, dynamic>>[];
    // Turns that finished while you were away (what a night egg counts).
    var awayLeft = away.clamp(0, n);
    for (var left = n; left > 0; left -= 50) {
      final chunk = min(left, 50);
      final chunkAway = min(awayLeft, chunk);
      awayLeft -= chunkAway;
      ops.add({
        'op': 'zoo.turn',
        'batchId': List.generate(
          16,
          (_) => _random.nextInt(16).toRadixString(16),
        ).join(),
        'n': chunk,
        if (chunkAway > 0) 'away': chunkAway,
        'day': localDayOf(now),
        'hour': now.hour,
        'machineId': machine,
      });
    }
    _applyLocal(ops);
  }

  void _enqueue(Future<void> Function() work) {
    _queue = _queue.then((_) => work()).catchError((_) {});
  }

  void _sendLater(Map<String, dynamic> op) {
    _unsent.add(op);
    _flushUnsent(_generation);
  }

  void _flushUnsent(int generation) {
    _enqueue(() async {
      if (!_current(generation) || _unsent.isEmpty || !isAccount) return;
      final batch = List<Map<String, dynamic>>.of(_unsent);
      Map<String, dynamic>? answer;
      try {
        answer = await _remote!.apply(batch);
      } catch (error) {
        if (!_current(generation)) return;
        debugPrint('zoo: write failed (${batch.length} ops): $error');
        // Kept, not dropped: every op is idempotent, so a retry is safe.
        _scheduleRetry(generation);
        return;
      }
      if (!_current(generation)) return;
      _failures = 0;
      if (answer == null) {
        // A 404 on a write: daemons were switched off since the read.
        _goOff(generation);
        return;
      }
      _unsent.removeRange(0, batch.length.clamp(0, _unsent.length));
      _adopt(answer);
    });
  }

  // ── local preferences: days used, the arrival hint ──────────────────────────

  /// The `days` habit: Harness used on three different local days.
  void noteDay() {
    if (!loaded) return;
    final now = _now();
    final day =
        '${now.year.toString().padLeft(4, '0')}-'
        '${now.month.toString().padLeft(2, '0')}-'
        '${now.day.toString().padLeft(2, '0')}';
    if (_days.add(day)) {
      while (_days.length > 7) {
        _days.remove((_days.toList()..sort()).first);
      }
      _savePrefs();
    }
    if (_days.length >= 3) habit('days');
  }

  int get daysUsed => _days.length;

  bool acknowledgeHint() {
    if (!needsHint) return false;
    _hintSeen = true;
    _savePrefs();
    notifyListeners();
    return true;
  }

  Future<Map?> _readJson(String key) async {
    try {
      final raw = await storage?.read(key);
      final decoded = raw == null ? null : jsonDecode(raw);
      return decoded is Map ? decoded : null;
    } catch (_) {
      // A missing or corrupt preference cannot block getting to work.
      return null;
    }
  }

  void _write(String key, Map<String, dynamic> value) {
    final data = jsonEncode(value);
    _saving = _saving.then((_) async {
      try {
        await storage?.write(key, data);
      } catch (_) {}
    });
  }

  void _saveLocal() =>
      _write(localZooKey, {'zoo': _local.toJson(), 'seeded': _seeded});

  void _savePrefs() {
    final scope = _scope;
    if (scope == null || isPreview) return;
    _write(prefsKey(scope), {
      'days': (_days.toList()..sort()),
      'hintSeen': _hintSeen,
    });
  }

  Future<void> flush() async {
    await _queue;
    await _saving;
  }

  @override
  void dispose() {
    _disposed = true;
    _retry?.cancel();
    unawaited(_events.close());
    super.dispose();
  }
}