wire/
answer.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//! What a Query comes back as: one shape per view, and the closed set
7//! of them.
8//!
9//! These are read shapes and nothing else. Every one is derived from the
10//! city's own state by a projection above this crate, so nothing here
11//! decides anything; what this module owns is that a page and a server
12//! agree on the field names, and that `Unavailable` is a real answer —
13//! a view this build does not evaluate yet says so by name rather than
14//! returning an empty result a reader would mistake for an empty city.
15
16use kernel::{
17    Address, ApprovalItem, Autonomy, ClusterKey, FileChange, GitOid, Restoration, Ruling, Seq,
18    TimeMs,
19};
20use serde::{Deserialize, Serialize};
21
22use crate::command::HaltScope;
23use crate::guide::GuideProgress;
24use crate::preference::PreferencesAnswer;
25
26mod automation;
27mod building;
28mod commits;
29mod config;
30mod cost;
31mod cost_of;
32mod doctor;
33mod document;
34mod document_bytes;
35mod document_versions;
36mod endpoints;
37mod evidence;
38mod find;
39mod git_status;
40mod github;
41mod harnesses;
42mod history;
43mod hunks;
44mod identity;
45mod known_hosts;
46mod listing;
47mod mcp_health;
48mod metrics;
49mod model_facts;
50mod note;
51mod prefix;
52mod preview;
53mod proposals;
54mod range;
55mod release;
56mod rounds;
57mod run_summary;
58mod scanning;
59mod sessions;
60mod skills;
61mod toolkits;
62mod usage;
63
64pub use automation::{AutomationAnswer, Cadence, ScheduledJob, WatchedSource};
65pub use building::{ArchiveLine, BlockedLine, BuildingAnswer, BuildingDoc};
66pub use building::{BuildingProgress, PlanRow, PursuitLine};
67pub use commits::{CommitAnswer, CommitAt, CommitsAnswer};
68pub use config::{
69    ConfigAnswer, ConfigLayer, SecondDomain, SettledEffort, SettledSecond, TuningDefaults,
70};
71pub use cost::{CostAnswer, UnpricedCalls};
72pub use cost_of::{CostOfAnswer, RUN_COSTS_MAX, RunCostsAnswer};
73pub use doctor::{DoctorAbsence, DoctorAnswer, DoctorCore, DoctorFault, DoctorInstall, DoctorItem};
74pub use doctor::{DoctorCoverage, DoctorCustody, DoctorCustodyLifetime, DoctorCustodyStore};
75pub use doctor::{DoctorGuarantee, DoctorGuaranteeAxis, DoctorSandbox, DoctorSandboxArm};
76pub use doctor::{DoctorNeed, DoctorState, DoctorTier, DoctorVerdict, DoctorVersion};
77pub use doctor::{DoctorNewest, DoctorPack, DoctorUnread, DoctorUpstream};
78pub use doctor::{DoctorSandboxMissing, SandboxArm};
79pub use document::{Coverage, DocumentAnswer, DocumentBody, DocumentState, HeldDocument};
80pub use document_bytes::{BYTES_WINDOW_MAX, BytesAnswer, ExportAnswer};
81pub use document_versions::{DocumentVersion, VERSIONS_MAX, VersionSource, VersionsAnswer};
82pub use endpoints::{ChosenSummary, EndpointSummary, EndpointsAnswer};
83pub use evidence::{EvidenceAnswer, EvidenceItem, EvidenceKind, Picture};
84pub use find::{FIND_MAX, FIND_WALK_MAX, FindAnswer, Walked};
85pub use git_status::{Drift, GitStatusAnswer};
86pub use github::{GithubLoginAnswer, GithubReading};
87pub use harnesses::{HarnessLine, HarnessState, HarnessesAnswer};
88pub use history::{HistoryAnswer, HistoryRangeAnswer};
89pub use hunks::{HunksAnswer, PatchLine, Withheld};
90pub use identity::{IdentityAnswer, StatedIdentity};
91pub use known_hosts::{KnownFace, KnownHost, KnownHostsAnswer};
92pub use listing::{Entry, EntryKind, ListingAnswer};
93pub use mcp_health::{McpHealthAnswer, McpServerHealth, McpState, McpToolLine};
94pub use metrics::MetricsAnswer;
95pub use model_facts::ModelFactsSummary;
96pub use note::{HandbackNote, Note, ReplyEnd, ReplyEnded, Speaker};
97pub use prefix::{ContentAnswer, PrefixAnswer, PrefixSegment, PrefixSlot, PrefixSource};
98pub use preview::PreviewAnswer;
99pub use proposals::{OfferedCard, OpenProposalsAnswer, ProposalCard, ProposalsAnswer};
100pub use range::RangeAnswer;
101pub use release::{InstallChannel, Registry, RegistryNewest, RegistryReading};
102pub use release::{ReleaseAnswer, ReleaseLine, UpdateHint};
103pub use rounds::{
104    Call, Closing, FrozenNames, Opening, Outcome, Output, RoundsAnswer, Timing, Turn, Used,
105};
106pub use run_summary::{RunSummary, Waiting};
107pub use scanning::{DoctorDrive, DoctorExclusion, DoctorScanning, DoctorUntold};
108pub use sessions::{SESSION_PREVIEW_MAX, SESSIONS_MAX, SessionLine, SessionStart, SessionsAnswer};
109pub use skills::{SkillLine, SkillShelf, SkillsAnswer};
110pub use toolkits::{Standing, ToolkitLine, ToolkitsAnswer};
111pub use usage::VersionAuthor;
112pub use usage::{
113    DayCount, ExportFormat, HeldSkill, McpServerUsage, McpToolUsage, McpUsageAnswer, McpUse,
114};
115pub use usage::{ShellCalls, ShellsAnswer, UsageExportAnswer, UsageKind, UseOutcome};
116pub use usage::{SkillAudit, SkillUsageAnswer, SkillUsageLine, SkillUse, SkillVersion};
117
118/// What moved between two checkpoints, one row per file, path order.
119///
120/// Path order rather than size order: somebody looking for one file finds
121/// it in the same place every time, and a list that reorders itself as
122/// the numbers change cannot be scanned twice.
123#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
124#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
125pub struct ChangesAnswer {
126    pub base: GitOid,
127    /// Absent when the comparison ran against the working tree.
128    pub head: Option<GitOid>,
129    pub files: Vec<FileChange>,
130}
131
132/// The most records one `History` answer may carry. A page asking for
133/// more gets this many; the whole ledger is not a thing to put on a
134/// socket, and a limit the caller cannot exceed is one fewer way for a
135/// client to make the server do unbounded work.
136pub const HISTORY_MAX: u32 = 500;
137
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
139#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
140pub struct CityAnswer {
141    /// Every active run and the latest frozen few, in RunId order;
142    /// `frozen` counts every frozen run, listed or not.
143    pub runs: Vec<RunSummary>,
144    pub active: u64,
145    pub frozen: u64,
146    /// One entry per building whose roadmap the city could read.
147    pub buildings: Vec<BuildingProgress>,
148    /// The standing goals this city is working towards, if any.
149    pub pursuits: Vec<PursuitLine>,
150    /// The scopes shut by `halt` and not yet released, in the shape a
151    /// `halt` frame names them. A page that has just opened has no
152    /// other way to learn that the city is stopped.
153    ///
154    /// The same type the command carries, not the ledger's string form:
155    /// a reader that had to take `building:<addr>` apart would be
156    /// writing a second copy of a grammar that already has one, and the
157    /// first client to get it wrong reported every shut building as
158    /// running.
159    pub halted: Vec<HaltScope>,
160    /// The last record of a history proved whole, when the proof has
161    /// found it so; absent while a served city is still proving it, or
162    /// after the proof found it broken (`crates/wire/spec/Answer.lean` §8-63).
163    pub proved: Option<Seq>,
164}
165
166/// What is waiting for a person, as the Ledger recorded it.
167///
168/// The whole item travels rather than a summary of it. An interface that
169/// groups identical questions needs the cluster key, and one that leads
170/// with the longest wait needs the arrival time; a summary type that
171/// dropped both forced the page to render every item as its own group
172/// under a sentence nobody wrote. `tainted` needs no special carriage
173/// here for the same reason - it is a field of the item itself.
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
176pub struct ApprovalsAnswer {
177    pub items: Vec<ApprovalItem>,
178}
179
180/// What a query returns. `Unavailable` is a real answer: a view this
181/// build does not evaluate yet says so by name, rather than returning an
182/// empty result a reader would mistake for an empty city.
183///
184/// `Eq` went when `History` arrived: a record's payload is arbitrary
185/// JSON, and JSON has no total equality. Nothing compared two answers
186/// for equality outside a test.
187#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
188#[serde(rename_all = "snake_case")]
189#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
190pub enum Answer {
191    History(Box<HistoryAnswer>),
192    HistoryRange(Box<HistoryRangeAnswer>),
193    Sessions(SessionsAnswer),
194    Changes(ChangesAnswer),
195    Commit(Box<CommitAnswer>),
196    City(CityAnswer),
197    Run(Option<Box<RunSummary>>),
198    Approvals(ApprovalsAnswer),
199    Cost(Box<CostAnswer>),
200    Endpoints(EndpointsAnswer),
201    KnownHosts(KnownHostsAnswer),
202    Harnesses(HarnessesAnswer),
203    Building(Box<BuildingAnswer>),
204    Inbox(InboxAnswer),
205    Discards(DiscardAnswer),
206    Registry(RegistryAnswer),
207    Archive(ArchiveAnswer),
208    Metrics(Box<MetricsAnswer>),
209    Governance(GovernanceAnswer),
210    Hunks(Box<HunksAnswer>),
211    Rounds(Box<RoundsAnswer>),
212    Evidence(EvidenceAnswer),
213    CostOf(CostOfAnswer),
214    RunCosts(RunCostsAnswer),
215    Listing(ListingAnswer),
216    Find(FindAnswer),
217    Document(Box<DocumentAnswer>),
218    Proposals(Box<ProposalsAnswer>),
219    OpenProposals(OpenProposalsAnswer),
220    Range(Box<RangeAnswer>),
221    Versions(Box<VersionsAnswer>),
222    Bytes(Box<BytesAnswer>),
223    Export(Box<ExportAnswer>),
224    Preview(Box<PreviewAnswer>),
225    /// A reply's text laid out (`crates/wire/spec/Answer/Preview.lean` §8-75): its closed blocks, and
226    /// the bytes they cover.
227    Reply(Box<documents::Laid>),
228    Commits(CommitsAnswer),
229    Doctor(Box<DoctorAnswer>),
230    Upstream(Box<DoctorUpstream>),
231    Prefix(Box<PrefixAnswer>),
232    Content(Box<ContentAnswer>),
233    Skills(Box<SkillsAnswer>),
234    GitStatus(Box<GitStatusAnswer>),
235    McpHealth(Box<McpHealthAnswer>),
236    SkillUsage(Box<SkillUsageAnswer>),
237    McpUsage(Box<McpUsageAnswer>),
238    UsageExport(Box<UsageExportAnswer>),
239    Shells(Box<ShellsAnswer>),
240    Toolkits(Box<ToolkitsAnswer>),
241    Release(Box<ReleaseAnswer>),
242    Preferences(Box<PreferencesAnswer>),
243    Config(Box<ConfigAnswer>),
244    Identity(Box<IdentityAnswer>),
245    Automation(Box<AutomationAnswer>),
246    GithubLogin(GithubLoginAnswer),
247    Guide(GuideProgress),
248    /// `reason` is the text of what stopped a view that tried to look
249    /// (`crates/wire/spec/Server.lean` D47); absent when the view names
250    /// the query alone.
251    Unavailable {
252        query: String,
253        #[serde(default, skip_serializing_if = "Option::is_none")]
254        reason: Option<String>,
255    },
256}
257
258/// Who answers for this city, and what was answered on the person's
259/// behalf.
260///
261/// One shape for both halves: a list of decisions with nobody named
262/// beside it does not say whether the person delegated them, and a
263/// delegation with nothing under it does not say whether it was ever
264/// used.
265#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
266#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
267pub struct GovernanceAnswer {
268    pub autonomy: Autonomy,
269    /// Every approval this city has answered, oldest first — the order
270    /// the ledger wrote them and the order a fold expects.
271    ///
272    /// The person's own answers are here too. A list holding only what
273    /// somebody else decided would make "I answered this" and "nobody
274    /// ever answered this" look the same, and who may answer is the
275    /// other field of this same answer.
276    pub decided: Vec<Decision>,
277}
278
279/// One approval, as it was answered.
280#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
281#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
282pub struct Decision {
283    /// The `ApprovalId` that was answered.
284    pub item: String,
285    pub verdict: Ruling,
286    /// What the person was shown when they answered: the answer covers
287    /// the group, not the one row.
288    pub cluster: ClusterKey,
289    pub at: TimeMs,
290}
291
292/// What waits in one room, without taking it.
293///
294/// Folded from the ledger rather than read off the queue: a queue that
295/// is read by being consumed cannot also be looked at, and a view that
296/// consumed what it showed would be a view that changes the thing it
297/// reports on.
298#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
299#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
300pub struct InboxAnswer {
301    pub addr: Address,
302    pub waiting: Vec<SignalLine>,
303}
304
305#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
306#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
307pub struct SignalLine {
308    pub id: String,
309    pub kind: String,
310    pub from: String,
311    pub at: TimeMs,
312    /// The first line of the signal's `text`; `None` when its payload
313    /// carries no text (`crates/wire/spec/Reading.lean` D39).
314    #[serde(default)]
315    pub first_line: Option<String>,
316}
317
318/// The Recycle Bin: what was discarded and how each row gets back.
319///
320/// A row without a way back cannot be constructed upstream, so every
321/// row here states one; `restored` says whether somebody already took
322/// it.
323#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
324#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
325pub struct DiscardAnswer {
326    pub rows: Vec<DiscardLine>,
327}
328
329#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
330#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
331pub struct DiscardLine {
332    pub path: String,
333    /// The way back, as the record kept it - the plan itself, not a
334    /// sentence about it.
335    ///
336    /// Composing the sentence is the interface's job and it already has
337    /// one authority for it (`client/src/views/record/bin.svelte`); a server that
338    /// also rendered the plan into words would be the second. `None`
339    /// means the record names a scheme this build cannot read, which the
340    /// interface shows as a row it will not invent an action for - the
341    /// row is never dropped, because hiding a discarded thing is worse
342    /// than admitting the plan is unreadable.
343    pub restoration: Option<Restoration>,
344    pub at: TimeMs,
345    pub restored: bool,
346}
347
348/// What this city has decided is worth keeping.
349#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
350#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
351pub struct RegistryAnswer {
352    pub assets: Vec<RegistryLine>,
353}
354
355#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
356#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
357pub struct RegistryLine {
358    pub addr: Address,
359    pub kind: String,
360    pub subject: String,
361    pub at: TimeMs,
362}
363
364/// Archive hits across every building, read from the shelves at the
365/// moment of asking. The files are the authority; an index kept beside
366/// them would be a second copy of what the disk says.
367#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
368#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
369pub struct ArchiveAnswer {
370    pub needle: String,
371    pub hits: Vec<ArchiveHit>,
372}
373
374#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
375#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
376pub struct ArchiveHit {
377    pub building: Address,
378    pub kind: String,
379    pub day: u64,
380    pub subject: String,
381}
wire/answer.rs

wire/
answer.rs
