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

wire/
answer.rs
