wire/answer/config.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 one address is actually governed by, and which file said so.
7
8use kernel::{Address, Effort, Proxying};
9use serde::{Deserialize, Serialize};
10
11/// Which file settled one value.
12///
13/// **Every value in a [`ConfigAnswer`] carries one.** A settings page
14/// that was told only the resolved figure could not say whether the
15/// person is looking at their own entry, at something the building
16/// inherited, or at the city's — so pressing "reset" and pressing
17/// nothing looked the same, and the page had to climb the ladder a
18/// second time to find out. This is that answer, stated once by the
19/// layer that resolved it.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
23/// The rungs are named as `city::Layer` names them, and the two lists
24/// are held together by the one match that turns the city's rung into
25/// this one: a wire that called the building's file `resident` while
26/// the ladder called the room's file that is a wire whose readers
27/// disagree with the run about which file they are looking at.
28pub enum ConfigLayer {
29 /// No file states the value, and the city's built-in figure is in
30 /// force. A layer rather than an absence, so the page that draws
31 /// the value is told the figure instead of keeping a copy of it.
32 Default,
33 /// The city's own `CONFIG.toml`, which covers every building.
34 City,
35 /// The building's file, which covers every room under it.
36 Building,
37 /// The room's own file, which covers one session.
38 Resident,
39}
40
41/// `[model] effort`, and the file that settled it.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
43#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
44pub struct SettledEffort {
45 pub effort: Effort,
46 pub from: ConfigLayer,
47}
48
49/// `[context] second_threshold`, and the file that settled it.
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
51#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
52pub struct SettledSecond {
53 /// A whole percent of the window, already taken by
54 /// `kernel::config::SecondThreshold`'s one construction point.
55 pub percent: u64,
56 pub from: ConfigLayer,
57 pub domain: SecondDomain,
58}
59
60/// The whole percents a file may state for the second rung, both ends
61/// included: the two figures `kernel::config::SecondThreshold`'s one
62/// construction point reads, answered so a page that states the span
63/// does not spell it a second time.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
65#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
66pub struct SecondDomain {
67 pub min: u64,
68 pub max: u64,
69}
70
71/// What an endpoint that settled nothing is called with.
72///
73/// **These are the gateway's figures, read out rather than restated.**
74/// A form that shipped its own numbers as placeholder text would make
75/// an endpoint attached through the form and one attached by import
76/// behave differently while the person had filled in nothing; the form
77/// draws what this carries, and the numbers have one home.
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
79#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
80pub struct TuningDefaults {
81 /// Where these figures were stated. No file on the ladder states
82 /// them today, so this is [`ConfigLayer::Default`]; it is answered
83 /// rather than implied so a page never decides for itself that a
84 /// figure is the build's own.
85 pub from: ConfigLayer,
86 /// How long one settled request may take, in total.
87 pub timeout_ms: u64,
88 /// The ceiling on making a failed request again, as
89 /// `kernel::Retries::stated` spells it: absent is "until this city
90 /// is halted", which is what this build asks for and what no
91 /// number says. Zero is a real answer and means "once, then
92 /// report".
93 pub request_max_retries: Option<u32>,
94 /// How long a streamed answer may stay silent before the call is
95 /// abandoned. Absent means a stream is held to the same bound as a
96 /// settled call, which is the only figure this city can state
97 /// without inventing one.
98 pub stream_idle_timeout_ms: Option<u64>,
99 /// Which calls go through the machine's proxy.
100 pub proxying: Proxying,
101}
102
103/// What one address is governed by, value by value, with the file each
104/// value came from.
105///
106/// Answered for an address rather than for the city, because the ladder
107/// has three rungs and only an address says which room's rung is in
108/// play. An address naming a building answers with two rungs climbed
109/// and no room entry, which is what a building with no open session is.
110#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
111#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
112pub struct ConfigAnswer {
113 /// The address the ladder was climbed for.
114 pub addr: Address,
115 /// How hard the model is asked to think here. Absent means no
116 /// layer stated it and the provider's own default answers, which
117 /// is a statement this city deliberately makes rather than filling
118 /// in a level nobody chose.
119 pub effort: Option<SettledEffort>,
120 /// Where the context reminder's second rung sits at this address.
121 /// Always answered: where no file states it, the figure is
122 /// `kernel::consts_policy::CTX_REMINDER_SECOND_DEFAULT` and the
123 /// layer is [`ConfigLayer::Default`].
124 pub second: SettledSecond,
125 /// Where the context reminder's first rung sits, as a whole percent
126 /// of the window: `kernel::consts_policy::CTX_REMINDER_FIRST_PERCENT`.
127 /// No layer moves it, so no layer travels with it. Always answered by
128 /// this build; absent only in a frame from a city written before it
129 /// was (`crates/wire/Spec.lean` D13).
130 #[serde(default)]
131 pub first: Option<u64>,
132 pub tuning: TuningDefaults,
133}