docs/generated/contracts.mdgenerated from code

Reference · 32 min read

doc-events

Contracts: doc-events.

Source: crates/lvcs-doc/src/document/events.rs.

ruston main
1/// A peer's Ed25519 public key (`lvcs_vocab::ids::SIGNATURE`),2/// written in `ID_ENCODING` on the API (discussion:owner/57).3#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]4pub struct PeerKey(#[serde(with = "crate::cbor::fixed")] pub [u8; 32]);56/// Who caused a change and when: event data, never read inside an action7/// (discussion:owner/55). `time_ms` becomes the change's commit time, which grant8/// windows are checked against (discussion:owner/58). The request edge builds it with the9/// live grant it checked the write against (discussion:owner/125): `signer` and10/// `grant` are what the change's record names and its signature signs, and11/// `device` the raw Ed25519 key of this daemon. The document writes the12/// record ([`crate::Record`]) from it in one place, and the record derives13/// the change's Loro peer ([`crate::change::peer_of`]).14#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]15pub struct Origin {16    pub signer: PeerKey,17    pub grant: GrantId,18    pub device: DeviceKey,19    /// Unix time in milliseconds, read by the shell when it accepted the20    /// request. The commit time is `time_ms / 1000`, floored: change times21    /// are in seconds (discussion:owner/55).22    pub time_ms: i64,23    /// Whether this daemon holds `signer`'s key, as the request edge found24    /// it when it built the origin. A change by a signer it doesn't hold is25    /// a write device's to sign (discussion:owner/300): the document builds it26    /// without taking it into its live state, asks for its signature, and27    /// takes it, persists it, and answers its request only once [`Signed`]28    /// returns it; [`SignFailed`] discards it and refuses the request29    /// ([`RejectReason::Unsigned`]). A later edit by the same signer waits30    /// in the document's context until then.31    pub held: bool,32    /// The landing the change is one of (discussion:owner/795), when the33    /// request lands several files at once.34    #[serde(default, skip_serializing_if = "Option::is_none")]35    pub landing: Option<crate::change::LandingMark>,36}3738/// The signature of a change a document asked for ([`SignRequest`]) didn't39/// come: the write device that holds the signer's key refused it, timed40/// out, or isn't connected (discussion:owner/300), and `reason` says which, for the41/// log. A document holding `change` unsigned and outside its live state42/// discards it and refuses the request that caused it with43/// [`RejectReason::Unsigned`]. One holding it in its live state (its44/// signer's key is this daemon's, which couldn't sign) drops it and every45/// own change built on it, signed and held back or not, and names each in46/// [`DocOutput::SignsDropped`] (perf-memory/1): none was stored or sent.47/// Every other document ignores it. When `local` (this daemon's own48/// keyring couldn't sign it: locked, an I/O error, a key not loaded yet),49/// the document first asks again, up to `SIGN_RETRY_MAX` times, each after50/// a wait it names in [`DocOutput::RetrySign`] (discussion:owner/706).51/// `incarnation` is the request's ([`SignRequest::incarnation`]), echoed:52/// a failure of a request another incarnation made is ignored, since a53/// different change can hold `change`'s id by then (f-perf/2).54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]55pub struct SignFailed {56    pub change: ChangeId,57    pub reason: String,58    /// Whether this daemon's own keyring failed, not a write device.59    #[serde(default)]60    pub local: bool,61    pub incarnation: u64,62}6364/// The wait a document named in [`DocOutput::RetrySign`] passed: it asks65/// for the signature of `change` again, when it still asks for it and66/// `attempt` is the retry it last scheduled (discussion:owner/706).67/// `incarnation` is the `RetrySign`'s, echoed: a wait another incarnation68/// named is ignored (f-perf/2).69#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]70pub struct RetrySigning {71    pub change: ChangeId,72    pub attempt: u32,73    pub incarnation: u64,74}7576/// Correlates a request with its output; chosen by the daemon shell, unique77/// per connection.78#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]79pub struct RequestId(pub u64);8081/// Replace `delete` code points at `pos` with `insert`.82#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]83pub struct Splice {84    pub pos: usize,85    pub delete: usize,86    pub insert: String,87}8889/// How a save treats the file's `meta.derived` flag (row 180).90///91/// The saving daemon sets it from its classification of the path. The text92/// kind treats a [`DiskEdit`] or [`Edit`] as derived when it is `Mark`, or93/// `Keep` while `meta.derived` is true at the document's live heads. A derived text save commits94/// the line diff from its base's text to its own (row 414), leaving its95/// whole text there, based where its author last looked (never96/// at the live heads), and puts `meta.derived` true. `Unmark` puts it false and saves as a text save97/// always does; `Keep` on a document that isn't derived saves the same98/// way, so a node with a stale view never re-enables text merging. A99/// binary save is whole already: it commits as it always does and puts100/// the flag as a text save would. An executable-bit change puts no flag.101#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]102pub enum DerivedFlag {103    /// No rule applies: the document's own flag decides.104    Keep,105    /// A positive rule marks the path derived.106    Mark,107    /// An explicit negation marks it not derived.108    Unmark,109}110111/// Splice `content`. Every splice's positions are Unicode code points in112/// the text at `base` (the heads the client last saw); splices are sorted by113/// `pos` and don't overlap. The document applies them on the author's own114/// branch (discussion:owner/75, discussion:owner/78, and discussion:owner/125): at `base` plus the115/// author's latest change of any kind (the last op of every Loro peer whose116/// record names `origin.signer`, since each device, grant, and epoch is its117/// own peer), translating the splices from the text at `base` onto that118/// version by character identity (discussion:owner/76: each deleted base character119/// is deleted only if still visible, and each insert lands just after the120/// nearest earlier base character still visible, or at the start), and121/// commits there at `origin.time_ms / 1000` seconds as `origin.record()`'s122/// peer. The empty `base` is the version before any change, which every123/// document holds. A `base` the document doesn't hold answers124/// [`DocOutput::Rejected`] with [`RejectReason::UnknownBase`]; splices that125/// are unsorted, overlapping, or out of bounds at a known `base` answer it126/// with [`RejectReason::OutOfBounds`] (discussion:owner/81).127///128/// A derived edit ([`DerivedFlag`]) applies its splices to the text the129/// document renders at `base` and commits the result whole there, after130/// the same bounds check against that text; one that changes nothing131/// there commits nothing and answers `Changed` with no splices.132#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]133pub struct Edit {134    pub req: RequestId,135    pub origin: Origin,136    #[serde(with = "crate::cbor::heads")]137    pub base: Vec<ChangeId>,138    pub splices: Vec<Splice>,139    /// How the edit treats `meta.derived`.140    pub derived: DerivedFlag,141}142143/// Read the rendered body, or the value at `pointer` (RFC 6901) into the144/// document's Loro structure. A control document renders no file: with145/// no pointer it reads its whole Loro structure (discussion:owner/4). Reads are146/// dispatched and journaled like any event. A pointer that147/// names nothing answers [`DocOutput::Rejected`] with148/// [`RejectReason::Failed`] (discussion:owner/81).149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]150pub struct Read {151    pub req: RequestId,152    pub pointer: Option<String>,153    /// For an event ledger, the page of its events to read154    /// (discussion:owner/562); every other kind reads as without it.155    #[serde(default, skip_serializing_if = "Option::is_none")]156    pub page: Option<Page>,157    /// For a page, only events of these kinds count, chosen before the158    /// page is cut (orchestrator/56): `count` is matching events, and the159    /// page's cursors say where the scan stopped. Empty takes every kind.160    #[serde(default, skip_serializing_if = "Vec::is_empty")]161    pub kinds: Vec<String>,162}163164/// A page of an event ledger's events (discussion:owner/562), each at most165/// `EVENT_READ_PAGE_MAX` events: those from position `from` on, or the166/// last `count`. Its read answers `{"events": [...], "next": <position>}`,167/// `next` the position after its last event, `null` once none is left.168#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]169pub enum Page {170    /// Up to `count` events from position `from`.171    From { from: u64, count: u32 },172    /// The last `count` events.173    Last { count: u32 },174    /// The last `count` events before position `before` (discussion:owner/638).175    Before { before: u64, count: u32 },176    /// Not events but what a publish's rule check reads of them, the177    /// ledger's [`crate::PriorIndex`] as JSON, however long the ledger.178    Prior,179}180181/// Release the document; the actor stops.182#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]183pub struct Close;184185/// The document took no event for `ACTOR_IDLE_SECS` (its handle's runtime186/// says so, discussion:owner/442): it stops unless it syncs with a node187/// (discussion:owner/584), and the next event starts its next incarnation.188#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]189pub struct IdleTick;190191/// The project's rester asks the document to rest early: the loaded192/// documents' stored bytes are past `LOADED_BYTES_BUDGET`193/// (session-29a3231b/2, owner/700). The first ask moves the document to194/// its `Asked` state and it answers [`DocOutput::Kept`]; asked again195/// there, it rests as on [`IdleTick`] when it may, else answers `Kept`196/// again. Any other event but the two broadcasts leaves `Asked` first.197/// A document unsettled with a joined node rests only on an ask that is198/// `unsettled_ok`, which the rester makes only under memory pressure199/// (request-flood/1, discussion:owner/776 as amended): it answers any other200/// `Kept` again, still `Asked`, however its rounds restarted.201#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]202pub struct RestAsked {203    pub unsettled_ok: bool,204}205206/// The document's store durably wrote change records (discussion:owner/792207/// step 1): each change's id with its record's first byte in the store's208/// file, its format header counted. The daemon tells it once the write is209/// synced, so a change counts as stored only once it is written; a load's210/// offsets come with its load, never as this event.211#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]212pub struct LedgerWritten {213    pub at: Vec<(ChangeId, u64)>,214}215216/// A change from the tree directory (discussion:owner/33, discussion:owner/47, discussion:owner/54, discussion:owner/63, discussion:owner/75, and217/// 78), authored by the daemon's default peer (discussion:owner/64). Every218/// kind of change commits on the author's own branch, at its base plus the219/// author's latest change of any kind (discussion:owner/78).220#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]221pub struct DiskEdit {222    pub origin: Origin,223    /// Assigned by the tree, increasing per tree. Handling this edit224    /// emits exactly one [`DocOutput::Rendered`], with this stamp as225    /// `after`, whether it committed, changed nothing, or faulted before226    /// rendering, so the tree can tell which save a render follows and227    /// its pending-save rule always completes (discussion:owner/75 and discussion:owner/78).228    pub stamp: u64,229    pub change: DiskChange,230    /// How the save treats `meta.derived`: a derived text save commits231    /// the whole `new_text` at the base the rule on [`DiskChange::Text`]232    /// chooses ([`DerivedFlag`]).233    pub derived: DerivedFlag,234    /// The watcher raised the read this save came from, for a local change:235    /// the user's own write (discussion:owner/818), copied from236    /// [`crate::tree_file::FsChanged::local_change`]. False for a scan's or237    /// a re-check's read, an op's save, and every record written before238    /// the field: its document's load is then a background one. Encoded239    /// only when true, so every other save's record is the bytes it was.240    #[serde(default, skip_serializing_if = "core::ops::Not::not")]241    pub local_change: bool,242}243244/// One version a tree's disk held (discussion:owner/668).245#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]246#[serde(transparent)]247pub struct LandedVersion(#[serde(with = "crate::cbor::heads")] pub Vec<ChangeId>);248249/// What changed on disk. A change that leaves the file as it was where it250/// would commit (see each variant) makes no commit, so a save reported251/// twice is absorbed (discussion:owner/75). A removal is no file document's change:252/// the tree removes the path from the namespace (`.lvcs/tree`, history row253/// 457).254#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]255pub enum DiskChange {256    /// A text save (discussion:owner/47, discussion:owner/66, discussion:owner/78, discussion:owner/79, discussion:owner/131, and discussion:owner/433).257    /// When the file renders as exactly `new_text` at the live heads (as258    /// text, not bytes), the save makes no commit and259    /// only renders (discussion:owner/79). A save with no `base` and no `loaded` is260    /// from a file its tree has no index entry for (discussion:owner/433): when261    /// the document's history holds `new_text` (its newest262    /// `REFUSED_SAVE_VERSIONS` versions), it makes no commit either and263    /// renders; when the document holds a file there, it is refused stale264    /// ([`DocOutput::SaveRefused`]) against the document's version, every265    /// differing line overlapping, so it is never inserted whole; otherwise266    /// it is a new file, committed at the genesis heads.267    ///268    /// Any other save takes as its base the heads a hook read (`loaded`,269    /// discussion:owner/117) when the document holds them, they equal or descend270    /// from the author's latest change, and the save is not strictly nearer271    /// `base`'s text; else `base` when the document holds it; else the272    /// genesis heads (discussion:owner/78). It diffs the base's text against273    /// `new_text` and applies the splices like an [`Edit`] on the author's274    /// own branch, at the base plus the author's latest change of any kind275    /// (discussion:owner/125), so the save lands as a concurrent change; a text save276    /// takes out a binary file's bytes. When the base's text is `new_text`277    /// and the file renders as text where the save would commit, nothing278    /// changes and no commit is made.279    /// A save is reported with [`DocOutput::StaleSave`] when its base's280    /// history lacks the author's latest change, or it took the genesis281    /// heads while the document held changes beyond them. Before it282    /// commits, a save made from an older version than the text the283    /// document shows is refused when the lines it changes overlap lines284    /// changed since that version, measured against the base plus the285    /// author's latest change: no commit, [`DocOutput::SaveRefused`], and a286    /// render of the document as it is (discussion:owner/296).287    Text {288        new_text: String,289        /// The version the file's tree last rendered or saved there, its290        /// index entry's heads (discussion:owner/433); `None` when it has no entry.291        #[serde(with = "crate::cbor::opt_heads")]292        base: Option<Vec<ChangeId>>,293        /// The heads of the version a hook read the file at (`track_read`,294        /// discussion:owner/117), which the tree recorded and this save takes.295        #[serde(with = "crate::cbor::opt_heads")]296        loaded: Option<Vec<ChangeId>>,297        /// `base` is an intent's (row 440), the save's base exactly; else298        /// the document diffs the save from whichever of `base` and its299        /// newest `REFUSED_SAVE_VERSIONS` versions is nearest it (300        /// discussion:owner/433).301        #[serde(default)]302        exact: bool,303        /// This tree's last save of this path is still unanswered, so `base`304        /// is older than the buffer: the save continues that one, and chains305        /// on the change it committed while that is its author's latest, else306        /// it is weighed from `base`.307        #[serde(default)]308        follows: bool,309        /// The versions this tree's disk held at the path, oldest first,310        /// at most `LANDED_VERSIONS` (discussion:owner/668): the only311        /// versions weighed as the save's base, and what shows which lines312        /// its writer saw.313        #[serde(default)]314        landed: Vec<LandedVersion>,315        /// `base` is a read its writer's hook reported (an intent naming316        /// its heads, row 440), as strong as `loaded`: it may delete317        /// another author's line (discussion:owner/668).318        #[serde(default)]319        reported: bool,320        /// The save is the claim of one peer's in-place write intent321        /// (discussion:owner/773): its tool changed the file where it stood322        /// (an `Edit` naming the text it replaced), so it was made from the323        /// disk's bytes. A held file's such save lands its own change.324        #[serde(default)]325        in_place: bool,326        /// The SHA-256 of the exact bytes the save's writer's tool started327        /// from, as one peer's intent named them (discussion:owner/777): the328        /// version that renders them is the save's read, as strong as329        /// `loaded`. Bytes no version renders prove nothing.330        #[serde(default)]331        read: Option<crate::tree_file::ContentHash>,332        /// A text this tree's disk held at the path that no version holds:333        /// its own last save, which the document took other than as it was334        /// written (merged, or with lines kept). The deletion guard weighs335        /// it as a version this disk held when no hook reported a read336        /// (discussion:owner/668, revised by secfix/43).337        #[serde(default)]338        held: Option<String>,339        /// `base` is this tree's own last save, taken exactly as the same340        /// buffer's next version (no intent): the document keeps it exact341        /// only when the text holds a line that save inserted, since a342        /// different writer's stale buffer is no continuation of it343        /// (ui-project-2x/25).344        #[serde(default)]345        own: bool,346        /// The bytes' modification time is at or after the landed time of347        /// the entry's own write on this disk, both known: they were348        /// written from the entry's version (discussion:owner/724). A save349        /// with no intent whose text equals an older version then restores350        /// that version from the entry; with neither this nor `exact`, nor351        /// a modification time before the entry's landing, it is refused352        /// stale.353        #[serde(default)]354        after_landed: bool,355        /// The hash of the bytes of this path's previous text save that356        /// its tree sent and had no answer for, from its index entry357        /// (discussion:owner/730): the document weighs its own change that358        /// renders them as a version this disk held, so a save whose359        /// render a crash lost is still this save's base, never diffed in360        /// again.361        saving: Option<crate::tree_file::ContentHash>,362    },363    /// A save of bytes that are not valid UTF-8: puts `meta.bytes` (last364    /// writer wins) and empties `content`, committed on the author's own365    /// branch at `base` (discussion:owner/78). No commit when the file already366    /// renders exactly these bytes there.367    Binary {368        #[serde(with = "crate::cbor::bytes")]369        bytes: Vec<u8>,370        /// The tree's newest known disk state of the file (discussion:owner/78);371        /// empty when it has none. An empty base, or one the document372        /// doesn't have, is the genesis heads: the author then saw nothing.373        #[serde(with = "crate::cbor::heads")]374        base: Vec<ChangeId>,375    },376    /// The executable bit changed: puts `meta.executable`, committed on377    /// the author's own branch at `base` (discussion:owner/78). No commit when378    /// the bit already has this value there.379    Executable {380        executable: bool,381        /// As for [`DiskChange::Binary`].382        #[serde(with = "crate::cbor::heads")]383        base: Vec<ChangeId>,384    },385}386387/// A file as a document renders it: its text, or its bytes when `meta`388/// holds a binary file's. A document with no change is the empty text.389#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]390pub enum FileBody {391    Text(String),392    Binary(#[serde(with = "crate::cbor::bytes")] Vec<u8>),393}394395/// Names a daemon-wide fact in the local journal (discussion:owner/233): ids rise396/// within a daemon run, and each daemon run starts them again at 0.397#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]398pub struct FactId(pub u64);399400/// A daemon-wide fact the shell hands to many documents (discussion:owner/233):401/// the journal holds it once, as a record no actor's, and each402/// recipient's entry names `id` in place of the event. The actor reads403/// `value` alone, so the id never reaches a context or a fingerprint.404#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]405pub struct Fact<T> {406    /// The journal's name for it.407    pub id: FactId,408    /// The fact.409    pub value: T,410}411#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]412pub enum DocEvent {413    Edit(Edit),414    Read(Read),415    DiskEdit(DiskEdit),416    /// A tree save the daemon refused (discussion:owner/360): its author may not417    /// make it, or the daemon's check refused it otherwise. A file418    /// document commits nothing of it. When the file already renders as419    /// the save's body, or did at one of its last `REFUSED_SAVE_VERSIONS`420    /// versions, the save is no change, only a disk the tree's renders421    /// have not reached, and it is answered as a save that changes nothing422    /// is, with [`DocOutput::Rendered`] carrying its stamp as `after`.423    /// Otherwise, or when weighing or that render faults, it emits only424    /// [`DocOutput::RefusalStands`] with the stamp, and the daemon keeps425    /// the refusal (discussion:owner/343). Every other kind426    /// takes it as a [`DiskEdit`].427    RefusedSave(DiskEdit),428    /// Emit [`DocOutput::Rendered`] for the current heads, for example to a429    /// tree that restarted.430    Render,431    /// The namespace's [`DocEvent::Render`] at a load ([`TellPaths`]):432    /// every file hears its path unless the router was told the listing433    /// already (tree-render/8). Every other kind takes it as foreign.434    TellPaths(TellPaths),435    /// Optional compaction tick: emit [`DocOutput::Compacted`] when a436    /// snapshot is due (discussion:owner/615). The daemon does not send437    /// it while snapshots are unbound to signed changes (owner/752).438    Compact,439    Close,440    /// No event came for `ACTOR_IDLE_SECS` ([`IdleTick`]).441    Idle,442    /// `SYNC_ASK_QUIET_MS` passed since it asked a node to resend443    /// ([`DocOutput::QuietAfter`], discussion:owner/810 rule 3): a444    /// [`Recheck::Quiet`].445    QuietTick,446    /// The rester asks it to rest early ([`RestAsked`]), settled only.447    RestAsked,448    /// The rester asks it to rest early under memory pressure449    /// ([`RestAsked`] `unsettled_ok`): unsettled with a node or not.450    RestPressed,451    /// Its store durably wrote change records ([`LedgerWritten`]).452    LedgerWritten(LedgerWritten),453    /// Its executor couldn't read an answer's stored changes454    /// ([`AnswerUnread`]).455    AnswerUnread(AnswerUnread),456    /// A re-check's chunk of held changes, read from the ledger file by457    /// its executor ([`RejudgeChanges`], discussion:owner/792 step 4).458    RejudgeChanges(RejudgeChanges),459    /// Its executor couldn't read a re-check's chunk ([`RejudgeUnread`]).460    RejudgeUnread(RejudgeUnread),461    /// An equivocation's held change, read from the ledger file by its462    /// executor ([`EvidenceHeld`], discussion:owner/792 step 5).463    EvidenceHeld(EvidenceHeld),464    /// Its executor couldn't read an equivocation's held change465    /// ([`EvidenceUnread`]).466    EvidenceUnread(EvidenceUnread),467    ReadAt(ReadAt),468    /// A [`ReadAt`] answered once the document holds its heads469    /// (discussion:owner/655); other kinds refuse it as they refuse a470    /// `ReadAt`.471    HeldRead(HeldRead),472    /// A [`HeldRead`]'s asker gave up on it (discussion:owner/655).473    ReadWithdrawn(HeldReadWithdrawn),474    /// Start syncing with a node (discussion:owner/30; `M3.doc`, `M3.sync`).475    NodeJoined(NodeJoined),476    /// Stop syncing with a node; a daemon-wide fact (discussion:owner/233).477    NodeLeft(Fact<NodeLeft>),478    /// Sync messages from nodes, oldest first, each verified whole before479    /// Loro sees it (history row 459).480    SyncIn(SyncBatch),481    /// The daemon's signature for a committed change (discussion:owner/459), or for482    /// a change a write device signed, which the document then takes into483    /// its live state ([`Origin::held`]).484    Signed(Signed),485    /// A change's signature didn't come ([`SignFailed`]).486    SignFailed(SignFailed),487    /// The wait before a signing retry passed ([`RetrySigning`]).488    RetrySigning(RetrySigning),489    /// The grants every change is verified against (from `.lvcs/caps`);490    /// a daemon-wide fact (discussion:owner/233), shared by every document491    /// that hears it, never copied into each (orchestrator/18).492    Grants(Fact<std::sync::Arc<GrantsKnown>>),493    /// The caps document settled with a node: that node's deferred sync494    /// messages get their last check (discussion:owner/108); a daemon-wide fact495    /// (discussion:owner/233).496    CapsSettled(Fact<CapsSettled>),497    /// What the previous incarnation judged of nodes' refusals498    /// ([`DocOutput::Judgments`]), sent after the grants as it loads: taken499    /// only while it holds for the ledger and grants (`JudgedMemo`).500    Remembered(JudgedMemo),501    /// Add a signed grant to the `.lvcs/caps` document. Boxed: a signed502    /// grant is much larger than most events.503    IssueGrant(Box<IssueGrant>),504    /// Show a derived file at a counted generation's heads (row 180).505    Pin(Pin),506    /// Resolve cursor pairs at the current heads (discussion:owner/156).507    Resolve(ResolveAnchors),508    /// Anchor a notification's range at past heads (discussion:owner/156; `M3.doc`).509    Anchor(AnchorRange),510    /// Does one set of heads descend from another (discussion:owner/120)?511    Descends(DescendsQuery),512    /// A [`HeldDescends`].513    HeldDescends(HeldDescends),514    /// Where a protected file's approved heads start (discussion:owner/120).515    Baseline(BaselineQuery),516    /// Put an entry into a channel document (discussion:owner/119). Boxed, like517    /// [`DocEvent::IssueGrant`]: an attestation carries a frontier.518    ChannelPut(Box<ChannelPut>),519    /// Read an approvals segment as a fold reads it (discussion:owner/805).520    ChannelFold(ChannelFold),521    /// Replace an action's log document's log with a failed run's522    /// (discussion:owner/500). Boxed, like [`DocEvent::ChannelPut`]: a log carries523    /// its run's tail.524    LogPut(Box<LogPut>),525    /// Append an entry to a plugin's entry ledger (discussion:owner/514). Boxed,526    /// like [`DocEvent::LogPut`]: an entry carries its JSON.527    EntryAppend(Box<EntryAppend>),528    /// Put a plugin's record into the `.lvcs/caps` document (529    /// discussion:owner/514). Boxed, like [`DocEvent::IssueGrant`].530    PluginPut(Box<PluginPut>),531    /// Add a hash to the `.lvcs/caps` document's signed allowlist532    /// (discussion:owner/128).533    AllowSecret(AllowSecret),534    /// Revoke grants in the `.lvcs/caps` document (discussion:owner/148). Boxed,535    /// like [`DocEvent::IssueGrant`].536    RevokeGrant(Box<RevokeGrant>),537    /// Purge files in the `.lvcs/caps` document (discussion:owner/614).538    /// Boxed, like [`DocEvent::RevokeGrant`].539    PurgeDocs(Box<PurgeDocs>),540    /// The path a file document's file is at (history row 457).541    PathKnown(crate::PathKnown),542    ResolvePath(crate::ResolvePath),543    ListFiles(crate::ListFiles),544    CreateFile(Box<crate::CreateFile>),545    MovePath(Box<crate::MovePath>),546    RemovePath(Box<crate::RemovePath>),547    RestorePath(Box<crate::RestorePath>),548    ResolveRemoved(crate::ResolveRemoved),549    ResolveRemoval(crate::ResolveRemoval),550}551552impl Origin {553    /// The record a change made under it names (discussion:owner/125): epoch 0,554    /// which a document whose refusals stopped that peer raises555    /// (`Ledger::writable`, history row 460).556    #[must_use]557    pub const fn record(&self) -> crate::Record {558        crate::Record {559            signer: self.signer,560            grant: self.grant,561            device: Some(self.device),562            epoch: 0,563        }564    }565566    /// Its commit time in Unix seconds, floored (discussion:owner/55).567    #[must_use]568    pub const fn time_s(&self) -> i64 {569        self.time_ms.div_euclid(1_000)570    }571}572573impl DocEvent {574    /// The daemon-wide fact this event delivers, when it is one (575    /// discussion:owner/233): the journal names it in place of the event.576    #[must_use]577    pub const fn fact(&self) -> Option<FactId> {578        if let Self::Grants(Fact { id, .. })579        | Self::CapsSettled(Fact { id, .. })580        | Self::NodeLeft(Fact { id, .. }) = self581        {582            Some(*id)583        } else {584            None585        }586    }587}588589/// Outputs a document actor hands to its effect sink. An applied change590/// emits, in order: one `SignRequest` per change it committed591/// (discussion:owner/459), `Changed`, `Rendered`; its `Persist` follows its [`Signed`],592/// once every own change it is built on is signed too (perf-memory/1). A593/// change whose signer this daemon doesn't hold ([`Origin::held`]) emits594/// only its `SignRequest`; its [`Signed`] emits `Persist`, `Changed`, and595/// `Rendered` (a text document's), and its [`SignFailed`] `Rejected` with596/// [`RejectReason::Unsigned`] when a request caused it. A [`DiskEdit`] that changes597/// nothing emits only `Rendered`. A [`DiskEdit`] whose handling faults598/// emits what it emitted before the fault (at most `Persist` and599/// `Changed`, in that order), then `Rendered`; only a render that faults600/// itself has no body to send (discussion:owner/78). A text save's `Rendered`601/// carries its stale or refused report.602#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]603pub enum DocOutput {604    /// It asked a node to resend: its executor sends it605    /// [`DocEvent::QuietTick`] after `SYNC_ASK_QUIET_MS` (discussion:owner/810606    /// rule 3); never carried on.607    QuietAfter,608    /// A re-check asks its executor for its next chunk of held changes,609    /// whole from the ledger file (discussion:owner/792 step 4); never610    /// carried on.611    RejudgeRead(RejudgeRead),612    /// An equivocation asks its executor for the held change its refused613    /// change overlaps, whole from the ledger file (discussion:owner/792614    /// step 5); never carried on.615    EvidenceRead(EvidenceRead),616    /// Own changes a refusal or a failed signature dropped: they will617    /// never be stored, so nothing may wait for them (discussion:owner/669618    /// and discussion:owner/717).619    SignsDropped(Vec<ChangeId>),620    /// The answer this step gives `req` speaks of own changes no store621    /// holds yet that no sign request of this step names for it: a write622    /// that changed nothing, answered at heads holding them, or a write623    /// device's change taken on one still unsigned. The answer is good624    /// only once each of `changes` is stored, and failed when one is625    /// dropped (discussion:owner/717).626    AnswerAwaits {627        req: RequestId,628        changes: Vec<ChangeId>,629    },630    /// This daemon's keyring failed to sign the own change `change`: its631    /// owner sends [`RetrySigning`] with this `attempt` back after632    /// `delay_ms`, and the document asks again then633    /// (discussion:owner/706). The change stays its own meanwhile, so the634    /// document doesn't rest and what waits on it keeps waiting.635    /// `incarnation` is the document's own, which the `RetrySigning`636    /// echoes (f-perf/2).637    RetrySign {638        change: ChangeId,639        attempt: u32,640        delay_ms: u64,641        incarnation: u64,642    },643    /// A change was applied. `splices` turn the live text at the previous644    /// heads into the text at `heads`, computed from the two (a645    /// deterministic diff, discussion:owner/75) rather than echoed from the request,646    /// so subscribers can patch their buffers; `req` is set when the change647    /// answers a request. `heads` are the live heads, the version of the648    /// text the splices make: what a push names, and they may name an own649    /// change no store holds yet. `stored`, set exactly when `req` is, are650    /// the heads the answer gives its asker (discussion:owner/720): those651    /// of what the store holds once the answer is good, the signed changes652    /// and the own changes the answer waits for with the own changes653    /// those are built on. They never name an own change the answer654    /// doesn't wait for, which may yet be dropped, so they are a durable655    /// base; they equal `heads` or are behind them.656    Changed {657        req: Option<RequestId>,658        #[serde(with = "crate::cbor::heads")]659        heads: Vec<ChangeId>,660        splices: Vec<Splice>,661        /// The namespace-confirmed path of a removed file revived without662        /// changing its document text; other changes carry none.663        revival: Option<String>,664        #[serde(default, with = "crate::cbor::opt_heads")]665        stored: Option<Vec<ChangeId>>,666        /// The file path the owning document holds at this step.667        #[serde(default)]668        path: Option<String>,669    },670    /// A request was refused; `reason` says why, so the daemon can answer671    /// `UNKNOWN_BASE` and `OUT_OF_BOUNDS` correctly (discussion:owner/81).672    Rejected {673        req: RequestId,674        reason: RejectReason,675    },676    /// Bytes to append to this document's store under `.lvcs/docs/`677    /// (discussion:owner/30): an incremental save, or a full compacted save that678    /// replaces earlier ones.679    Persist {680        changes: Vec<crate::SignedChange>,681        evidence: Vec<crate::Evidence>,682        /// The merged saves among `changes`, by the id the document keeps683        /// each as (discussion:owner/728): the store writes their records684        /// before the changes, in the same append.685        merged: Vec<crate::change::MergedSave>,686        /// The file path the owning document holds at this step.687        #[serde(default)]688        path: Option<String>,689    },690    /// A compacted snapshot candidate (discussion:owner/615): Loro's own691    /// encoding of every signed change held. The daemon discards it while692    /// snapshots are unbound to signed changes (owner/752). Never synced.693    Compacted(Vec<u8>),694    /// The whole file at `heads`, emitted after every applied change, once695    /// for every [`DiskEdit`] (also one that changes nothing or faults,696    /// discussion:owner/78), and on [`DocEvent::Render`], for the tree actor697    /// (discussion:owner/33, discussion:owner/63, and discussion:owner/75).698    /// `after` is the `stamp` of the [`DiskEdit`] whose handling produced699    /// this render, and `None` for any other render (discussion:owner/75).700    /// `touched` is what that edit changed when it committed a text save,701    /// a binary save, or a removal, at `heads`, and `None` for every other702    /// render, an executable-bit change included (discussion:owner/165).703    /// `moved` is whether `heads` differ from the previous render's.704    Rendered {705        /// What the document holds: each peer's counters below its end.706        #[serde(default)]707        known: Vec<(u64, i32)>,708        #[serde(with = "crate::cbor::heads")]709        heads: Vec<ChangeId>,710        body: FileBody,711        executable: bool,712        after: Option<u64>,713        touched: Option<Touched>,714        /// Whether `heads`, `path`, or the pin differ from the document's715        /// previous render's in this incarnation: a render that moves none716        /// of them is news only to its reader or the tree whose save it717        /// answers, never to the router's index (request_flood).718        moved: bool,719        /// Set when the render shows one head of a derived document alone720        /// (row 180's winner rule): the head shown, and each other head721        /// whose text differs, with its signer. `None` for every other722        /// render.723        superseded: Option<Superseded>,724        /// What the render reports about the text save it answers: stale725        /// (discussion:owner/66 and discussion:owner/75), or refused stale and726        /// uncommitted (discussion:owner/296 and discussion:owner/389). `None` for every other727        /// render.728        report: Option<Box<crate::SaveReport>>,729        /// The path the document last got through [`DocEvent::PathKnown`]:730        /// `None` while it knows none or once the file is removed.731        path: Option<String>,732        /// Whose save the render follows: the signer of the tree save's733        /// origin (the tree's participant, or the peer whose write734        /// notification the change answered, discussion:owner/513); `None` for735        /// every render that follows no save.736        #[serde(default)]737        by: Option<PeerKey>,738    },739    /// Events a ledger took, by append or sync, since it last said so740    /// (discussion:owner/515), oldest first, each as `event.read` answers it741    /// (`EventRecord`), for the subscriptions their address matches.742    EventsAppended(Vec<serde_json::Value>),743    /// The answer to a [`Read`]: the live value at the live `heads`, so a744    /// reader sees its own unsigned edits (discussion:owner/720). A read's745    /// heads may name a change not yet stored, which is gone if its746    /// signature fails; only an answer's heads ([`DocOutput::Changed`]'s747    /// `stored`) are a durable base.748    ReadDone {749        req: RequestId,750        #[serde(with = "crate::cbor::heads")]751        heads: Vec<ChangeId>,752        value: ReadValue,753    },754    /// The [`DocEvent::RefusedSave`] of this stamp would change the755    /// document, or couldn't be weighed, so its refusal stands: nothing was756    /// committed or rendered, and the file keeps its bytes (discussion:owner/343757    /// and 360). It is the save's only answer.758    RefusalStands(u64),759    /// An [`Edit`] to a `file` document was refused, uncommitted (760    /// discussion:owner/310): its base is older than the text the document shows, and the761    /// lines it changes overlap lines another peer changed since762    /// that base, measured as a stale save is (discussion:owner/296). It answers763    /// the edit's request in place of `Changed` or `Rejected`.764    EditRefused {765        req: RequestId,766        overlap: StaleOverlap,767    },768    ReadAtDone(ReadAtDone),769    /// A sync message for a node (discussion:owner/30; `M3.doc`, `M3.sync`).770    SyncOut(SyncOut),771    /// Nothing more to send a node until it answers (discussion:owner/68).772    SyncSettled(SyncSettled),773    /// A node's sync message was taken, whatever came of it774    /// (session-29a3231b/2).775    SyncTook(SyncTook),776    /// A rested document answered a node without loading, and runs no777    /// more for it (channel-judge/5).778    SyncRested(SyncRested),779    /// This file processed a node's leave after the sync imports ahead of it.780    /// Its owner may return that node's incoming byte charges now.781    NodeLeftDone(DeviceKey),782    /// A node's whole sync message was rejected (discussion:owner/68).783    SyncRejected(SyncRejected),784    /// A committed change awaits its signature (discussion:owner/459).785    SignRequest(SignRequest),786    /// The answer to [`DocEvent::Resolve`].787    Resolved(Resolved),788    /// The answer to [`DocEvent::Anchor`].789    Anchored(Anchored),790    /// The `.lvcs/caps` document's render.791    CapsRendered(CapsRendered),792    /// The owner purged this document, at this address: a deleted file's793    /// or a plugin's entry ledger (discussion:owner/614). Its machine794    /// stopped for good, and its ledger is to be deleted. Its last output.795    Purged(String),796    /// The answer to [`DocEvent::RestAsked`] of a document that didn't797    /// rest (session-29a3231b/2): `could_rest` when only because it was798    /// its first ask, so asked again before its next step it rests; else799    /// it is busy or holds what resting would lose (owner/700).800    /// `unsettled` when a joined node isn't settled with it yet801    /// (request-flood/1, discussion:owner/776 as amended): a sweep rests802    /// it only when nothing settled can rest, or under memory pressure.803    Kept {804        could_rest: bool,805        unsettled: bool,806    },807    /// A document that answered [`DocOutput::Kept`] may rest now, said on808    /// a later step than the answer (f-perf/9, f-perf/22): what a stalled809    /// rester waits for (owner/700 rule 3), said once per such answer.810    Restable,811    /// The signer behind each Loro peer of the document's verified812    /// changes, for attribution (`M3.doc`, `M3.daemon`).813    Signers(Signers),814    /// The answer to [`DocEvent::Descends`] (discussion:owner/120).815    DescendsDone(DescendsDone),816    /// The answer to [`DocEvent::Baseline`] (discussion:owner/120).817    BaselineDone(BaselineDone),818    /// A channel document's render (discussion:owner/119).819    ChannelRendered(ChannelRendered),820    /// The answer to [`DocEvent::ChannelFold`] (discussion:owner/805).821    ChannelFolded(ChannelFolded),822    /// The revocations a node of the `.lvcs/caps` document holds823    /// (discussion:owner/326).824    NodeRevocations(NodeRevocations),825    /// A peer this document writes as, or holds changes of, is stopped by826    /// its own checks (history row 460, discussion:owner/549): every change of it827    /// from `from` on, and every change depending on one, is dropped; its828    /// record's writer goes on at the next epoch. `reason` is the row 459829    /// outcome.830    PeerRefused {831        record: crate::Record,832        from: i32,833        reason: crate::change::Refusal,834        /// The grants it was judged under, by digest (discussion:owner/787):835        /// the store keeps them with the refusal.836        #[serde(default)]837        grants: Option<[u8; 32]>,838    },839    /// A node's refusal this document's own checks contradict, judging by840    /// the same rules and grants (discussion:owner/549): the changes stay.841    VerdictDisputed(crate::sync::VerdictDisputed),842    /// What this document holds set aside as unreadable changed843    /// (discussion:owner/671 rule 2): each peer holding such changes, with844    /// how many it set aside. Empty once none is. It goes to the router,845    /// which `status` asks, so no document is asked in turn (rule 6).846    Unreadable {847        address: String,848        peers: Vec<(u64, u32)>,849        /// A sender of what it set aside judged by rules newer than this850        /// binary's: the node needs an upgrade, rather than only perhaps.851        #[serde(default, skip_serializing_if = "core::ops::Not::not")]852        newer_rules: bool,853    },854    /// This step lifted refusals for authorization its grants moved past855    /// (discussion:owner/787): the lifted changes come back only as a node856    /// sends them again, so every link joins the document, as for a change857    /// of it, and its join's answer shows each node what it lacks. Without858    /// it a document loaded from rest for the grants move, joined with no859    /// node, asked nobody (release-qual/4, revoke_under_load).860    Lifted,861    /// The namespace document's answer to a query naming its request.862    Files(crate::FilesAnswer),863    /// How a namespace step moved files (the tree renames on disk).864    PathsChanged(Vec<crate::PathChange>),865    /// What the document holds in memory beside its ledger, in bytes:866    /// its re-check's kept audit of the history (`HistoryAudit`), charged867    /// to the rester with its stored bytes so the memory budget sees it868    /// (discussion:owner/776). Emitted when it changes; 0 once forgotten.869    Resident {870        bytes: u64,871    },872    /// What it judged of nodes' refusals, as it rests: the next873    /// incarnation's [`DocEvent::Remembered`], while it still holds874    /// (`JudgedMemo`).875    Judgments(JudgedMemo),876    /// Each node's latest input stepped, as it rests (mixed-version/4).877    Stepped(Vec<(DeviceKey, u64)>),878    /// The document's live heads moved in this step: the heads now, each879    /// with the Merkle digest of the span it ends, for the router's880    /// frontier (`DocShown.heads`). Emitted once, at the end of every step881    /// of every kind that moved them.882    HeadsShown(Vec<crate::frontier::HeadDigest>),883    /// The path a file is at now, from the namespace document, for the884    /// daemon to send to that file's document (`.lvcs/files/<id>`) as885    /// [`DocEvent::PathKnown`].886    PathKnownFor(crate::PathKnown),887    /// A loading namespace is about to tell its whole listing, its digest888    /// differing from the router's: the daemon sends the router889    /// `router::Relisting` ahead of the [`Self::PathKnownFor`] that890    /// follow, so the router's `Listed` un-names what the telling left out891    /// (r3-join/19).892    Relisting,893    /// A namespace step made the collision rule show a node under another894    /// name (history row 458): `wanted` is the path its name gives, `shown`895    /// the `<stem>~<tag><ext>` path it shows as, and `writer` the signer of896    /// the change that last created, renamed, or moved it. Emitted once per897    /// node while it stays collided.898    PathCollided {899        file: crate::FileId,900        wanted: String,901        shown: String,902        writer: PeerKey,903    },904    /// A namespace step brought a removed file back at `path` with its905    /// file id (`RestorePath`, history row 458): `remover` signed the906    /// removal it undid, when the namespace holds that change.907    FileRestored {908        file: crate::FileId,909        path: String,910        remover: Option<PeerKey>,911    },912}913914/// Why a request answered [`DocOutput::Rejected`] (discussion:owner/81). Only an915/// [`Edit`] is rejected for its base or splices; a [`DiskEdit`] is never916/// rejected (one with an unknown base commits at the genesis heads,917/// discussion:owner/78).918#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]919pub enum RejectReason {920    /// The edit's `base` is empty or names heads the document doesn't have.921    UnknownBase,922    /// The edit's splices are unsorted, overlapping, or out of bounds at its923    /// known `base`.924    OutOfBounds,925    /// Anything else: Loro or another callback faulted while answering926    /// the request, a read pointer names nothing, or the actor was closed.927    Failed,928    /// The write device that holds the edit's signer's key didn't sign its929    /// change (it refused, timed out, or isn't connected, discussion:owner/300):930    /// nothing was written.931    Unsigned,932}933934/// What a [`Read`] returns.935#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]936pub enum ReadValue {937    /// No pointer, in a file document: the rendered file.938    Body(FileBody),939    /// The value at the pointer, as JSON text; with no pointer, in a940    /// control document, the whole document.941    Json(String),942}943944/// The journaled fingerprint of a document actor, the one content check the945/// journal keeps beside each entry's trace (discussion:owner/286).946///947/// It holds the document's live heads, how much of its store the948/// incarnation loaded, and a digest of its durable context949/// (discussion:owner/32, discussion:owner/84, discussion:owner/222, and discussion:owner/286).950#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]951pub struct DocFingerprint {952    #[serde(with = "crate::cbor::heads")]953    pub heads: Vec<ChangeId>,954    /// How many ledger records (changes, evidence, and refusals) the955    /// store held when the incarnation loaded (`LoadDoc::records`): replay956    /// loads exactly that prefix of the store.957    pub records: u64,958    /// The `HASH` of the canonical CBOR array of four items: the live959    /// heads, each with the Merkle digest of the span it ends960    /// (`Ledger::head_digests`, so equal digests are equal histories); the961    /// sync state its kind journals (the grants known and what it holds962    /// back); the [`Pin`]'s heads, or null with none (always null but in a963    /// file document); and the path the document last got through964    /// [`DocEvent::PathKnown`] (`PathState`, null but in a file document).965    /// Nothing else of the context is covered: each node's sync state,966    /// rebuilt from the incarnation's own events, and the outputs, which967    /// the heads and the events already decide.968    #[serde(with = "crate::cbor::fixed")]969    pub digest: [u8; 32],970}971972/// Show a derived `file` document at a counted generation's heads (row 180).973///974/// `heads` are the heads of the counted generation main's visible975/// frontier shows, or `None` for no generation. While set, every render, read, and read at heads of a976/// version that includes `heads` shows the file at them (the greatest of977/// them alone when several), hiding every other head as the winner rule978/// does and naming each in `Rendered.superseded`; a version that doesn't979/// include them, or a document that doesn't hold them, is shown by the980/// winner rule. A pin that changes what the live document shows renders.981/// Every other kind ignores it.982#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]983pub struct Pin {984    #[serde(with = "crate::cbor::opt_heads")]985    pub heads: Option<Vec<ChangeId>>,986}987988/// The state label of the machine a document actor runs, which its kind's989/// layout selects (discussion:owner/82): `file` documents run the text machine,990/// the caps document, a channel, and every other kind their own.991#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]992pub enum DocLabel {993    Text(DocLifecycleStates),994    Caps(CapsLifecycleStates),995    Channel(ChannelLifecycleStates),996    Namespace(NamespaceLifecycleStates),997    Log(LogLifecycleStates),998    Entry(crate::kinds::entry::machine::EntryLifecycleStates),999}10001001impl sml::StateName for DocLabel {1002    fn name(&self) -> &'static str {1003        match self {1004            Self::Text(label) => label.name(),1005            Self::Caps(label) => label.name(),1006            Self::Channel(label) => label.name(),1007            Self::Namespace(label) => label.name(),1008            Self::Log(label) => label.name(),1009            Self::Entry(label) => label.name(),1010        }1011    }1012}10131014/// Does `heads`, a set of this document's heads, equal or descend from1015/// `from` (discussion:owner/120)? The `channels` actor asks it to decide1016/// supersession and approved heads, which only a document can tell. File1017/// documents, and the namespace document for the tree heads a frontier1018/// names (discussion:owner/694), answer with exactly one [`DescendsDone`]: [`Descent::Yes`] when every change in `from` is in1019/// the history of `heads`, `No` when one is not, and `Unknown` when either1020/// set is empty or names a change the document doesn't hold. Every other1021/// kind, and a closed actor, answers `Unknown`. `req` is the shell's.1022#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]1023pub struct DescendsQuery {1024    pub req: RequestId,1025    #[serde(with = "crate::cbor::heads")]1026    pub heads: Vec<ChangeId>,1027    #[serde(with = "crate::cbor::heads")]1028    pub from: Vec<ChangeId>,1029}10301031/// A [`DescendsQuery`] that waits for its heads (discussion:owner/660): a file1032/// document that lacks either side's heads defers it with sml's defer queue1033/// and answers it after the sync or save that brings them. At most1034/// `HELD_READS_MAX` wait in one document, shared with held reads; past that,1035/// and in every other kind, it is answered as a plain query is. Its asker's1036/// watchdog withdraws it (`HeldReadWithdrawn`).1037#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]1038pub struct HeldDescends {1039    /// The query.1040    pub query: DescendsQuery,1041}10421043/// The answer to a [`DescendsQuery`].1044#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]1045pub struct DescendsDone {1046    pub req: RequestId,1047    pub outcome: Descent,1048}10491050/// Where a protected file's approved heads start (discussion:owner/120 and discussion:owner/122):1051/// a `file` document answers with exactly one [`BaselineDone`] holding the1052/// heads after its genesis and its owner-signed import change (the record1053/// `[owner, GrantId::OWNER, null]` at time 0 on top of genesis,1054/// discussion:owner/125), or its genesis heads when it has no import. Every other1055/// kind, and a closed actor, answers `heads: None`. `req` is the shell's.1056#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]1057pub struct BaselineQuery {1058    pub req: RequestId,1059}10601061/// The answer to a [`BaselineQuery`]. A read (discussion:owner/720): its1062/// `heads` are read from every change the document holds, so they may1063/// name an import not yet stored, which is gone if its signature fails;1064/// only an answer's heads ([`DocOutput::Changed`]'s `stored`) are a1065/// durable base.1066#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]1067pub struct BaselineDone {1068    pub req: RequestId,1069    #[serde(with = "crate::cbor::opt_heads")]1070    pub heads: Option<Vec<ChangeId>>,1071    /// The first path the namespace placed the file at, when told.1072    #[serde(default, skip_serializing_if = "Option::is_none")]1073    pub first_path: Option<String>,1074}