wire/answer/
skills.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 building can do, by the shelf each capability sits on.
7//!
8//! Three shelves in one answer because a reader needs them together to
9//! make sense of any: the city's library is the stock any building may
10//! admit, the building's own shelf is what only it keeps, and the
11//! external shelves are directories the city mounts read-only from
12//! elsewhere on this machine. A line is the same seven facts on either
13//! shelf, so there is one row type and the shelf is what differs.
14
15use kernel::{Address, B3Hash, RunId};
16use serde::{Deserialize, Serialize};
17
18/// Which shelf a holding sits on, and where its document is.
19///
20/// One value rather than a shelf name beside a path, because a holding
21/// is on one shelf and at one place, and two fields would let them
22/// disagree: a row that says `library` and points outside the city is a
23/// state no shelf can be in.
24///
25/// Named rather than implied by which list it arrived in, so a page
26/// that shows three shelves in one list can still say where a skill
27/// came from - which is the question a person asks when two shelves
28/// hold the same name and the nearer one wins.
29///
30/// **The two city arms are `Query::Document`'s input; the external arm
31/// is not.** A skill on a shelf outside the city has no address, and one
32/// invented for it would send a reader to a file that is not there.
33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "snake_case")]
35#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
36pub enum SkillShelf {
37    /// The city's central stock, under the reserved prefix.
38    Library(Address),
39    /// This building's own shelf, inside the building.
40    Building(Address),
41    /// A directory outside the city that the city's configuration
42    /// mounts read-only: which shelf of that list this is, and the
43    /// document's path from the shelf's root.
44    External { index: u32, path: String },
45}
46
47/// One shelved skill.
48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
49#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
50pub struct SkillLine {
51    pub name: String,
52    /// The section the shelf files it under. Empty for a skill on an
53    /// external shelf: that tree is another harness's, it files skills
54    /// one directory per skill with no section above them, and a
55    /// section invented here would be this city's guess about a layout
56    /// it does not own.
57    pub section: String,
58    /// Which shelf, and where the document is on it.
59    pub shelf: SkillShelf,
60    /// The first non-empty line of the document, which is what its
61    /// author wrote to describe it.
62    pub disclosure: String,
63    /// What the whole document hashed to when this scan read it.
64    pub hash: B3Hash,
65    /// Whether this building's reading room admits it. A skill on the
66    /// shelves that the room does not admit costs a run nothing and is
67    /// still worth seeing: it is the list a person edits.
68    pub admitted: bool,
69    /// The runs that were frozen with this exact hash pinned, newest
70    /// last. Empty means nothing has used it, which is a different
71    /// fact from nothing having recorded it - every run records its
72    /// pins, so an empty list is an answer.
73    pub pinned_by: Vec<RunId>,
74}
75
76/// The shelves one building reads from.
77#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
78#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
79pub struct SkillsAnswer {
80    pub building: Address,
81    /// Every shelf, city stock first, then this building's own, then the
82    /// external shelves in the order the configuration lists them;
83    /// within a shelf, section then name order. [`SkillShelf`] says
84    /// which shelf a row came from; the scan that fills this list owns
85    /// the order, and nothing here re-sorts it.
86    pub skills: Vec<SkillLine>,
87    /// Names this building's reading room admits that no shelf holds.
88    /// Shown to the person who wrote the list, since only they can fix
89    /// it.
90    pub missing: Vec<String>,
91}
wire/answer/skills.rs

wire/answer/
skills.rs
