ScheduledReceiptLog class final

Append-only JSONL receipt trail for scheduled messages (gh-1180 AC4).

One line per lifecycle event so a post-mortem can distinguish "timer never fired" (a scheduled line with no matching delivered) from "wake refused" (a wake_refused line with its reason) without reading source:

• queue-side: scheduled (id, dueMs, to, text), delivered (id, to, dueMs, lagMs), delivery_failed (id, error), scan_failed (error);
• host-side (the CLI wake path): wake_attempted (lane, ids), turn_started, wake_refused (lane, reason).

The trail lives at <messagesRoot>/_scheduled/receipts.jsonl — the record scans read *.json entries only, so the log never joins a sweep or a delivery. Best-effort by contract: a failing write is reported through onError and NEVER breaks scheduling or waking (append always completes normally). Appends ride the backend's appendFile, so concurrent writers interleave whole lines, never tear them; in-process appends are serialized to keep line order stable.

Constructors

ScheduledReceiptLog({required ExecutionEnv env, required String path(), DateTime clock()?, void onError(String text)?})

Properties

hashCode → int

The hash code for this object.

no setter, inherited

onError → void Function(String text)?

Host-visible notice when a receipt cannot be persisted (same channel as the queue's onError — the CLI prints [sched] lines).

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

append(String event, Map<String, Object?> fields) → Future<void>

Appends one event. Never throws — the trail is best-effort.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited