wire/answer/
run_summary.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4// Copyright (c) 2026 2youg1 and the sprawling contributors
5
6//! One run as a reader who never saw its stream needs it
7//! (`crates/wire/spec/Reading.lean` D34 for `waiting`).
8
9use kernel::{Address, EventKind, RunId, Seq, TimeMs};
10use serde::{Deserialize, Serialize};
11
12/// One run, as a reader needs it. The client folds the live stream for
13/// itself; this shape is what a query answers about runs it never saw,
14/// which is why it carries the position rather than the whole history.
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
16#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
17pub struct RunSummary {
18    pub run: RunId,
19    pub who: String,
20    pub frozen: bool,
21    pub last_seq: Seq,
22    pub last_kind: EventKind,
23    /// The room the run works in, from its `run_started` record. `who`
24    /// cannot say it: that is the author of the first record, which is
25    /// the city. Absent when the view saw no opening for this run.
26    pub addr: Option<Address>,
27    /// When the run began, from the same record.
28    pub started: Option<TimeMs>,
29    /// How the run ended, as its `run_frozen` record says. Absent while
30    /// it runs, and when the view never saw the freeze.
31    pub completion: Option<String>,
32    /// The branch of the last pull request the run opened; a pull
33    /// request in the city is named by its branch and has no number.
34    pub pr: Option<String>,
35    /// What the run waits for the person to allow. Present exactly when
36    /// `last_kind` is `approval_requested`.
37    pub ask: Option<String>,
38    /// What the person asked for, as the run's `run_started` record says.
39    /// Absent when the view never saw the opening or the task was empty.
40    pub task: Option<String>,
41    /// What finishing looks like, from the same record, read the same way.
42    pub goal: Option<String>,
43    /// The room the run stopped on a synchronous `send` to hear from,
44    /// and until when; absent while it waits for nobody, and always
45    /// absent once it froze (`crates/wire/spec/Reading.lean` D34).
46    /// Defaulted, so an answer from a build without the field still
47    /// reads.
48    #[serde(default)]
49    pub waiting: Option<Waiting>,
50}
51
52/// What a run waits for: the room it spoke to, and the instant on the
53/// city's clock at which the wait ends without a reply. An instant
54/// rather than the time left, because an answer is cached and carried,
55/// and a count of milliseconds left is wrong once it leaves the city.
56#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
57#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
58pub struct Waiting {
59    pub on: Address,
60    pub until: TimeMs,
61}
wire/answer/run_summary.rs

wire/answer/
run_summary.rs
