///|
/// One line on a Loci engine's stdout JSONL stream: the contract between
/// `loci serve` and every client that reads it — the TUI, the desktop host,
/// and any script piping the stream.
///
/// Events carry rendered *values*, never rendered *text*. `Trail` hands over
/// the residue chain, not a box-drawn panel, which is what lets three surfaces
/// present the same run without any of them reimplementing the walk.
///
/// `to_json` is the only writer and `parse` its inverse; `parse_test` pins the
/// round trip per variant.
pub(all) enum Event {
  /// First line of every stream. `version` lets a client refuse an engine it
  /// cannot read instead of silently misparsing it.
  Ready(version~ : Int32, engine~ : String)

  // ── locus inhabitation ─────────────────────────────────────────────────
  /// A session entered `locus`. Carries the trail so a client that attached
  /// mid-run has the entry context without a second request.
  Entered(locus~ : Locus, trail~ : Trail)
  /// The full residue chain for one locus, newest first.
  TrailListed(trail~ : Trail)
  /// Every known locus with its most recent visit — the `where` answer.
  Located(loci~ : Array[Locus])
  /// A residue was filed, closing a session.
  ResidueFiled(residue~ : Residue)

  // ── substrate ──────────────────────────────────────────────────────────
  /// An epoch was sealed at `root`.
  Sealed(epoch~ : Int32, root~ : String)
  /// Content reached the store. `disposition` is the daemon's OCI verdict:
  /// "stored", "forwarded", "bypassed" or "rejected".
  Stored(digest~ : String, disposition~ : String)
  /// Counts from a tree diff, as `daemon tree diff` reports them.
  Diffed(added~ : Int32, removed~ : Int32, changed~ : Int32, unchanged~ : Int32)

  // ── run lifecycle ──────────────────────────────────────────────────────
  /// Anything a surface should surface but that is not itself a result.
  Diagnostic(severity~ : Severity, message~ : String)
  /// Last line of the stream. Non-zero `code` means the run failed.
  Finished(code~ : Int32)
} derive(Eq, Debug)