recordPendingWait method

Future<String> recordPendingWait({ required String resultText, required Map<String, dynamic> arguments, })

The pending-wait write path (issue #1380 AC5): a successful schedule_message arms a timer — this records the pending-wait obligation whose text is the timer's reason (verbatim from the call) and whose source points at the scheduled-message record, so the fired timer re-enters a context that already knows why it exists. Structured-engine sessions only (a classic session never grows ledger records, E3). Returns the human-readable outcome for the attach site; failures are REPORTED here and swallowed by the afterToolCall wrapper — the schedule itself already succeeded and must never fail because its ledger note could not land.

Implementation

Future<String> recordPendingWait({
  required String resultText,
  required Map<String, dynamic> arguments,
}) async {
  if (_effectiveCompactionEngine() == CompactionEngine.classic) {
    return 'classic engine — no obligations ledger';
  }
  final session = _session;
  if (session == null) return 'no session is open — no ledger';
  final scheduledId = RegExp(r'^scheduled (\S+) for ').firstMatch(resultText);
  if (scheduledId == null) {
    return 'schedule_message result did not carry a scheduled id — no '
        'pending-wait entry written';
  }
  final text = arguments['text'];
  final writer = await _obligationsWriterFor(session);
  final payload = writer.ingestPendingWait(
    text: text is String ? text : '',
    sourceRecordId: scheduledId.group(1)!,
  );
  if (payload == null) {
    return 'pending-wait already recorded for this timer';
  }
  try {
    await session.appendCustomEntry(
      customType: obligationsLedgerRecordType,
      data: payload,
    );
  } on Object {
    return 'recording the pending-wait failed — the snapshot did not '
        'persist; it rides the next successful ledger write';
  }
  return 'pending-wait recorded: the ledger now carries the reason this '
      'timer exists';
}