moveTo method

Future<String?> moveTo(String? entryId, { String? summary, Object? details, bool? fromHook, })

Moves the active leaf to entryId (or the tree root when null), appending a leaf record. When summary is provided, also appends a branch_summary record and returns its id; otherwise returns null.

Ported from pi's Session.moveTo.

Implementation

Future<String?> moveTo(
  String? entryId, {
  String? summary,
  Object? details,
  bool? fromHook,
}) async {
  // gh-1589: the seal fences the leaf move too — a sealed session must
  // not write leaf/branch_summary records any more than message appends
  // (the straggler that calls this post-teardown loses nothing that was
  // owed: branch navigation is a live-session affordance).
  final seal = _seal;
  if (seal != null && seal.isSealed) {
    seal.rejectWrite('leaf_move');
    return null;
  }
  if (entryId != null && await _storage.getEntry(entryId) == null) {
    throw SessionException(
      'Entry $entryId not found',
      code: SessionErrorCode.notFound,
    );
  }
  await _storage.setLeafId(entryId);
  if (summary == null) return null;
  final record = BranchSummaryRecord(
    id: await _storage.createEntryId(),
    parentId: entryId,
    timestamp: DateTime.now(),
    fromId: entryId ?? 'root',
    summary: summary,
    details: details,
    fromHook: fromHook,
  );
  await _storage.appendEntry(record);
  return record.id;
}