docs/generated/contracts.mdgenerated from code

Reference · 26 min read

tree

Contracts: tree.

Source: crates/lvcs-doc/src/tree_file/mod.rs.

ruston main
1/// Path of a file relative to the tree root, `/`-separated.2#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]3#[serde(transparent)]4pub struct TreeFilePath(pub String);56/// SHA-256 of a file's bytes (`lvcs_vocab::ids::HASH`), computed by the7/// shell. Serializes as a 32-byte byte string.8#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]9pub struct ContentHash(#[serde(with = "cbor::fixed")] pub [u8; 32]);1011impl ContentHash {12    /// SHA-256 of no bytes: an empty file's hash.13    pub const EMPTY: Self = Self([14        0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f, 0xb9,15        0x24, 0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b, 0x78, 0x52,16        0xb8, 0x55,17    ]);18}1920/// A file's state on disk as the tree knows it: what a version puts21/// there.22#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]23pub enum OnDisk {24    /// No file.25    #[default]26    Absent,27    /// A file.28    Present {29        /// SHA-256 of its bytes.30        hash: ContentHash,31        /// Its executable bit.32        executable: bool,33    },34}3536/// A file's identity on its filesystem (discussion:owner/433): the device and37/// inode on Unix, the volume serial number and file index on Windows. An38/// atomic write's rename gives the path a new one.39#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]40pub struct FileId {41    /// The device, or the volume serial number.42    pub device: u64,43    /// The inode, or the file index.44    pub file: u64,45}4647/// What a stat of a file found, without reading it (discussion:owner/433).48#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]49pub struct FileStat {50    /// Its size in bytes.51    pub size: u64,52    /// Its modification time, Unix milliseconds.53    pub modified_ms: i64,54    /// Its identity.55    pub identity: FileId,56    /// Its executable bit.57    pub executable: bool,58    /// When its inode last changed, Unix nanoseconds, 0 where the platform59    /// keeps no such time (Windows): no program can set it, so a same-size60    /// write that puts the modification time back still moves it. A stat61    /// stored without it never equals a new one, so that file is read once62    /// and takes the new stat.63    #[serde(default)]64    pub changed_ns: i64,65}6667/// A write the tree emitted and the shell has not yet confirmed: its68/// version's heads and what it puts on disk. The executor puts it in the69/// index before it writes the file, so after a crash the disk holding it is70/// still the tree's own bytes (discussion:owner/433).71#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]72pub struct PendingWrite {73    /// The written version's heads.74    #[serde(with = "cbor::heads")]75    pub heads: Vec<crate::ChangeId>,76    /// What it puts on disk.77    pub on_disk: OnDisk,78}7980/// The bytes of a save the tree sent and has not had its answer for (81/// discussion:owner/730): their hash and the stat the shell read them82/// with. `hash` is SHA-256 of the save's bytes; the version the document83/// already holds behind it is found by rendering, and crash-persisted in84/// the `index`'s entry, so a save whose render a crash lost is still85/// weighed from its own change.86#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]87pub struct SavingSave {88    /// SHA-256 of the save's bytes.89    pub hash: ContentHash,90    /// The stat the shell read those bytes with (`None` for a rename's91    /// removal-shaped change without one, as [`FsChanged::stat`] names).92    pub stat: Option<FileStat>,93}9495/// One path's entry in the tree's index (discussion:owner/433): the version the96/// tree last rendered or saved there, what that puts on disk, the stat97/// its own last write landed with (`None` when the entry came from a save,98/// or a render the disk already held), and a write still in flight.99#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]100pub struct IndexEntry {101    /// The version's heads.102    #[serde(with = "cbor::heads")]103    pub heads: Vec<crate::ChangeId>,104    /// What it puts on disk.105    pub on_disk: OnDisk,106    /// The stat its bytes were last seen with: the tree's own write, or107    /// the read a save or an import took them from (discussion:owner/433). A stat108    /// equal to it clears the file unread.109    pub landed: Option<FileStat>,110    /// The version this one replaced on disk, when the entry moved on from111    /// another: bytes written before this version landed were made from it112    /// (discussion:owner/433).113    #[serde(default, with = "cbor::opt_heads")]114    pub replaced: Option<Vec<crate::ChangeId>>,115    /// The stat `replaced`'s own write landed with, when the tree saw it116    /// land: bytes modified before it were made before `replaced` was on117    /// disk, so not from it (integrity-lines/5: a read older than two118    /// landings).119    #[serde(default)]120    pub replaced_landed: Option<FileStat>,121    /// The version is this tree's own save's, as it put it on disk: its122    /// next save with no intent is the author's next version of the same123    /// buffer, diffed against it exactly (discussion:owner/433).124    #[serde(default)]125    pub saved: bool,126    /// The versions this disk held, oldest first, the newest this entry's,127    /// at most `LANDED_VERSIONS` (discussion:owner/668).128    #[serde(default)]129    pub landed_versions: Vec<crate::LandedVersion>,130    /// A write emitted and not yet confirmed.131    #[serde(default)]132    pub pending: Option<PendingWrite>,133    /// The stat of the bytes this tree's last save took, once that save's134    /// answer is written over them: a read with this stat is those bytes135    /// again (a read made before the write, arriving after it), which the136    /// document already holds, so it is never saved again (orchestrator/15).137    #[serde(default)]138    pub taken: Option<FileStat>,139    /// This tree's own save's text when the document took it other than140    /// as written (merged, with lines kept, or refused): the disk held it141    /// and no version holds it, and a buffer may have been made from it, so142    /// the next text save carries it to the deletion guard143    /// (discussion:owner/668, revised by secfix/43). Kept as the entry moves144    /// on; the next save the document renders as written ends it.145    #[serde(default)]146    pub unversioned: Option<String>,147    /// A save the tree sent and has not had its answer for yet (a save in148    /// flight, discussion:owner/730): its bytes' hash and the stat the149    /// shell read them with. Set before the save goes to the document,150    /// cleared when the save's render or refusal settles; a crash between151    /// the two keeps it, so the next save of the path carries the hash and152    /// the document weighs the save that is in flight with the rest.153    pub saving: Option<SavingSave>,154    /// The bytes a refused save left on disk, which no version holds, and155    /// the writer it was refused as (unproven-base/1): kept so that after a156    /// restart that writer's named intent may still rebase them, as it may157    /// before one. `None` when the disk keeps no refused bytes, or their158    /// writer can't be proven.159    #[serde(default, skip_serializing_if = "Option::is_none")]160    pub held_by: Option<HeldBy>,161}162163/// Refused bytes the disk keeps, and whose they are ([`IndexEntry::held_by`]).164#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]165pub struct HeldBy {166    /// The refused save's writer.167    pub writer: PeerKey,168    /// The bytes it left on disk.169    pub body: OnDisk,170}171172impl IndexEntry {173    /// Whether this entry's version is known to have been on this disk174    /// (discussion:owner/668): the shell saw its bytes land, or it is this175    /// tree's own save. A write still out, or the version a refused save's176    /// document showed, is no evidence.177    pub(crate) fn held_on_disk(&self) -> bool {178        (self.landed.is_some() || self.saved)179            && self.on_disk != OnDisk::Absent180            && !self.heads.is_empty()181    }182}183184/// The tree's index as the shell read it, the first event of every185/// incarnation (discussion:owner/433).186#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]187pub struct IndexLoaded {188    /// Every indexed path's entry, in path order.189    pub entries: Vec<(TreeFilePath, IndexEntry)>,190}191192/// What a stat of an indexed path found, as the tree opens or after193/// lost events (discussion:owner/433): `None` when no file is there.194#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]195pub struct Statted {196    /// The file's path.197    pub path: TreeFilePath,198    /// What the stat found.199    pub stat: Option<FileStat>,200}201202/// The user asked to save `path` (`lvcs add`), which the index holds and203/// main holds no file at (discussion:owner/821 (B)): the tree forgets the204/// entry and reads the file as unseen, so it is saved as a file the tree205/// has no entry for. The start never sends it: it only tells the peer the206/// index names. Nothing on disk or on main is removed, renamed or207/// overwritten because of it.208#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]209pub struct NotOnMain {210    /// The indexed path main lacks.211    pub path: TreeFilePath,212}213214/// A peer declared it is about to change the file at `path` in the host's215/// tree with its own tool (`intent`, row 440): the tree's next change of216/// the file within `INTENT_TTL_MS` of `now_ms` is that peer's, against217/// `base`, or with none against the version the tree shows the peer's tool218/// then: the path's index entry when the intent arrives (none for a new219/// file).220#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]221pub struct Intended {222    /// The file's path.223    pub path: TreeFilePath,224    /// The peer.225    pub signer: PeerKey,226    /// The heads the peer read the file at; `None`: the path's entry's.227    #[serde(with = "cbor::opt_heads")]228    pub base: Option<Vec<crate::ChangeId>>,229    /// The shell's Unix time in milliseconds when the intent arrived.230    pub now_ms: i64,231    /// Whether the write is only the harness's guess that a command it232    /// runs may write the path (decision 624's `WriteBody.quiet`), rather233    /// than the tool's own declaration. A real declaration answers a234    /// change over a standing quiet intent of another peer, because its235    /// tool said it was about to make exactly this write.236    #[serde(default)]237    pub quiet: bool,238    /// What its writer said it will do to the range (`WriteBody.op`, or239    /// `None` for one that didn't say): `adding` answers a change that put240    /// the file there, `removing` one that took it away, `changing` or241    /// `None` either (o-codex/3).242    #[serde(default)]243    pub op: Option<WriteOp>,244    /// The tool changes the file where it stands (an `Edit` naming the245    /// text it replaces), so its write is made from the disk's bytes246    /// (discussion:owner/773).247    #[serde(default)]248    pub in_place: bool,249    /// The SHA-256 of the exact bytes the tool starts from, as the250    /// writer's hook read them (`WriteBody.read_hash`,251    /// discussion:owner/777).252    #[serde(default)]253    pub read_hash: Option<ContentHash>,254}255256/// A peer's intent on the file at `path` ended (a `done` write event, rows 440 and 515).257/// It still stands for `MTIME_SLACK_MS` after `now_ms`, for a change258/// its tool made no later than then, which the watcher may read after the end.259#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]260pub struct IntentEnded {261    /// The file's path.262    pub path: TreeFilePath,263    /// The peer.264    pub signer: PeerKey,265    /// The shell's Unix time in milliseconds when the intent ended.266    pub now_ms: i64,267}268269/// What the shell found at a path.270#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]271pub enum DiskState {272    /// A file, as the shell read it.273    Present {274        /// Its bytes.275        #[serde(with = "cbor::bytes")]276        content: Vec<u8>,277        /// SHA-256 of `content`.278        hash: ContentHash,279        /// Its executable bit.280        executable: bool,281    },282    /// No file (removed, or never written).283    Absent,284}285286/// A `notify` change, an answer to [`TreeFileOutput::Read`], or a refused287/// [`TreeFileOutput::WriteFile`] or [`TreeFileOutput::RemoveFile`], with what288/// the shell read.289///290/// Paths under `.lvcs/`, never-sync paths, and symbolic links never arrive.291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]292pub struct FsChanged {293    /// The file's path.294    pub path: TreeFilePath,295    /// What the shell read there.296    pub state: DiskState,297    /// The `Origin` of every `DiskEdit` this change produces, filled in by298    /// the shell: the daemon's default peer (discussion:owner/64) and the299    /// Unix time in milliseconds when it read the file.300    pub origin: Origin,301    /// The `heads` of the `WriteFile` or `RemoveFile` this change answers302    /// when the shell refused it because the file's hash wasn't its303    /// `expect`, and `None` for a `notify` change or a read (304    /// discussion:owner/75). Serializes as null or an array of 32-byte byte strings.305    #[serde(with = "cbor::opt_heads")]306    pub refused: Option<Vec<crate::ChangeId>>,307    /// The file's stat as the shell read it (discussion:owner/433); `None` when308    /// there is no file.309    #[serde(default)]310    pub stat: Option<FileStat>,311    /// The shell read the file because its watcher saw a local change (the312    /// user's own write, discussion:owner/818), not for a scan or a313    /// re-check: event data from the handler that raised the read. Every314    /// `DiskEdit` this change produces carries it. Encoded only when315    /// true, so every other read's record is the bytes it was.316    #[serde(default, skip_serializing_if = "core::ops::Not::not")]317    pub local_change: bool,318}319320/// The shell finished a [`TreeFileOutput::WriteFile`] or321/// [`TreeFileOutput::RemoveFile`]; advances the disk base. After a removal322/// `hash` is `None` and `executable` is false.323#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]324pub struct WriteDone {325    /// The file's path.326    pub path: TreeFilePath,327    /// SHA-256 of what was written; `None` after a removal.328    pub hash: Option<ContentHash>,329    /// The executable bit written; false after a removal.330    pub executable: bool,331    /// Heads of the document version that was written.332    #[serde(with = "cbor::heads")]333    pub heads: Vec<crate::ChangeId>,334    /// The written file's stat, taken right after the rename (335    /// discussion:owner/433); `None` after a removal.336    #[serde(default)]337    pub stat: Option<FileStat>,338}339340/// A document's `DocOutput::Rendered`, addressed to the tree by the shell,341/// which also hashes the rendered bytes (`None` for a removed file). The342/// shell also sends one with `removed` set when the namespace removed the343/// file (`PathsChanged` with no `to`, history row 457): its render takes the344/// file off disk.345#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]346pub struct DocRendered {347    /// The file's path.348    pub path: TreeFilePath,349    /// The rendered version's heads.350    #[serde(with = "cbor::heads")]351    pub heads: Vec<crate::ChangeId>,352    /// The rendered body.353    pub body: FileBody,354    /// SHA-256 of the rendered bytes; `None` for a removed file.355    pub hash: Option<ContentHash>,356    /// The rendered executable bit.357    pub executable: bool,358    /// `DocOutput::Rendered.after`: the `stamp` of this tree's `DiskEdit`359    /// whose apply produced the render, `None` for any other render360    /// (discussion:owner/75); for a removal, the stamp of this tree's361    /// [`TreeFileOutput::RemovePath`] that the namespace took.362    pub after: Option<u64>,363    /// The namespace removed the file: the render takes it off disk.364    #[serde(default)]365    pub removed: bool,366    /// What the document holds, each peer's counters below its end.367    #[serde(default)]368    pub known: Vec<(u64, i32)>,369    /// Set by the tree: the path's first render since its index loaded,370    /// so what it doesn't hold a crash lost (secfix/39).371    #[serde(default)]372    pub first_render: bool,373}374375/// What the shell found of the filesystem under this tree's root as the376/// incarnation starts (discussion:owner/361): whether it tells names apart that377/// differ only by ASCII case or only by Unicode normalization, from a probe378/// file it looked up under its case-swapped and its decomposed names. On379/// such a root an ASCII name is looked up by name alone; elsewhere a name380/// that resolves is told apart from the names it collides with.381#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]382pub struct Probed {383    /// The root tells ASCII case and Unicode normalization apart.384    pub case_sensitive: bool,385}386387/// A hook read the file at `path`, and the bytes it read hash to `hash`388/// (`track_read`, discussion:owner/117): the exact base of the peer's next389/// save of the file.390#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]391pub struct Loaded {392    /// The file the hook read.393    pub path: TreeFilePath,394    /// SHA-256 of the bytes it read.395    pub hash: ContentHash,396}397398/// A hook's tool is about to edit the file at `path` (`track_edit`,399/// discussion:owner/117): which version does it edit?400///401/// Answered with exactly one [`TreeFileOutput::Located`] echoing `req`, the402/// shell's id for the request.403#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]404pub struct Locate {405    /// The shell's id for the request, which the answer echoes.406    pub req: RequestId,407    /// The file the tool edits.408    pub path: TreeFilePath,409}410411/// The protected-path gate held a render of the file at `path` (412/// discussion:owner/122): the document's `heads` and the render's `after`, which the413/// shell sends in place of the [`DocRendered`] it held.414#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]415pub struct Held {416    /// The file whose render was held.417    pub path: TreeFilePath,418    /// The document's heads in the held render.419    #[serde(with = "cbor::heads")]420    pub heads: Vec<crate::ChangeId>,421    /// The held render's `after`.422    pub after: Option<u64>,423}424425/// The daemon refused this tree's save `after` of the file at `path`,426/// for any reason (discussion:owner/343): nothing reached the document, and the427/// file keeps the bytes the save reported until a later save of it is428/// answered.429#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]430pub struct SaveRefused {431    /// The file whose save was refused.432    pub path: TreeFilePath,433    /// The refused `DiskEdit`'s stamp.434    pub after: u64,435    /// The refused save's writer; absent when the writer cannot be proven.436    #[serde(default)]437    pub signer: Option<PeerKey>,438    /// For a save its document refused stale (discussion:owner/389), the version439    /// the document showed then, which the file takes as its newest disk440    /// base, so a write of that version's text back to the file, or a441    /// change redone on it, is measured from it; `None` for every other442    /// refusal.443    pub shown: Option<ShownVersion>,444}445446/// No document took this tree's save `after` of the file at `path` (its447/// project stopped, its load failed, or a hand-off dropped it), so the448/// edit was never committed, and no answer will come. It isn't refused:449/// the file is read again and its bytes are saved again450/// (discussion:owner/439). A save that is only slow to be answered is never451/// taken as lost.452#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]453pub struct SaveLost {454    /// The file whose save was lost.455    pub path: TreeFilePath,456    /// The lost `DiskEdit`'s stamp.457    pub after: u64,458    /// The lost save's writer, whose bytes a hold keeps.459    #[serde(default)]460    pub signer: Option<PeerKey>,461}462463/// A version of a file the document showed, as a disk base: its heads and464/// what it puts on disk (discussion:owner/389).465#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]466pub struct ShownVersion {467    /// The version's heads.468    #[serde(with = "cbor::heads")]469    pub heads: Vec<crate::ChangeId>,470    /// SHA-256 of its bytes.471    pub hash: ContentHash,472    /// Its executable bit.473    pub executable: bool,474    /// The version the refused save was made from.475    #[serde(with = "cbor::heads")]476    pub from: Vec<crate::ChangeId>,477}478479/// The shell could not run a [`TreeFileOutput::WriteFile`] because another480/// process holds the file open (Windows: reading or replacing it failed481/// with a sharing violation, raw OS error 32, or access denied, 5; the482/// held-rename row refining discussion:owner/252): the write's own payload, so the483/// tree can write it again, and the shell's time. Never sent elsewhere.484#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]485pub struct WriteHeld {486    /// The file the write was for.487    pub path: TreeFilePath,488    /// The bytes it would have written.489    #[serde(with = "cbor::bytes")]490    pub content: Vec<u8>,491    /// SHA-256 of `content`.492    pub hash: ContentHash,493    /// The executable bit it would have set.494    pub executable: bool,495    /// The heads of the document version it would have written.496    #[serde(with = "cbor::heads")]497    pub heads: Vec<crate::ChangeId>,498    /// The shell's Unix time in milliseconds when the write was held.499    pub now_ms: i64,500}501502/// The time a [`TreeFileOutput::Wake`] for `path` named came: the shell's503/// clock reached it (discussion:owner/161's wall-clock loop).504#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]505pub struct Tick {506    /// The file the wake was for.507    pub path: TreeFilePath,508    /// The wake's `at_ms`, which ties the tick to the wake it answers.509    pub at_ms: i64,510    /// The shell's Unix time in milliseconds when it sent the tick.511    pub now_ms: i64,512}513514/// A write through a descriptor is under way at each of `paths` (a data515/// change and no close since, discussion:owner/131): the tree stages its writes516/// and removals to them until a [`Closed`] at or above each.517#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]518pub struct Writing {519    /// The paths being written.520    pub paths: Vec<TreeFilePath>,521}522523/// The shell's read of `path` found the file moving under it (524/// discussion:owner/150, row 415): the tree stages its writes to it until the settled525/// re-read's [`Closed`].526#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]527pub struct Moved {528    /// The file read.529    pub path: TreeFilePath,530}531532/// How the shell paired a [`Renamed`] (session-062e63ba/14).533#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]534pub enum RenameBy {535    /// The kernel named both paths (inotify's cookie).536    Cookie,537    /// `to` holds the inode a candidate's entry landed with, and the538    /// candidate left the disk in the same batch (FSEvents names no539    /// pair, and APFS doesn't reuse inode numbers).540    Identity,541}542543/// A rename on disk left one of `from` and put the file or directory at544/// `to`: the tree keeps its document, as `lvcs mv` does, moving the entry545/// and asking the namespace ([`TreeFileOutput::MovePath`]). The shell546/// sends this before it reads either path, and reports `to` and each of547/// `from` as usual right after, so a pair the tree doesn't take is an548/// ordinary removal and create.549#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]550pub struct Renamed {551    /// The path, or with [`RenameBy::Identity`] the paths, it left.552    pub from: Vec<TreeFilePath>,553    /// Where it is now.554    pub to: TreeFilePath,555    /// How it was paired.556    pub by: RenameBy,557    /// The stat of `to`; `None` for a directory.558    pub stat: Option<FileStat>,559    /// With [`RenameBy::Identity`], SHA-256 of `to`'s bytes as the shell560    /// read them: a new inode holding exactly the bytes a candidate's561    /// version put on disk is that file moved (a cross-device `mv`, `cp`562    /// then `rm`, or a platform that keeps no inode, secfix/42). `None` for563    /// a directory or a file it couldn't read.564    pub hash: Option<ContentHash>,565    /// `to` is a directory; read only with [`RenameBy::Identity`]. A file566    /// paired by identity is the candidate file itself and a directory a567    /// candidate directory, never one in the other's place568    /// (integrity-disk/4).569    #[serde(default)]570    pub dir: bool,571    /// With `dir`, the first file below `to` whose stat `stat` is: a gone572    /// directory is where `to` was only when it held that file exactly at573    /// the same place below it (r3-join/15). `None` for a file, and in a574    /// record made before the field.575    #[serde(default)]576    pub first: Option<TreeFilePath>,577    /// The disk's author.578    pub origin: crate::Origin,579}580581/// The namespace's answer to [`TreeFileOutput::MovePath`]: `moved`, or582/// refused, so the rename is an ordinary removal and create after all.583#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]584pub struct MoveDone {585    /// Where it was moved to.586    pub to: TreeFilePath,587    /// Whether the namespace took it.588    pub moved: bool,589    /// The disk's author.590    pub origin: crate::Origin,591}592593/// The writes under way at each of `under` and below it ended, an empty594/// path standing for every path (discussion:owner/131): the tree writes what it595/// staged for them, each path's oldest first. The shell sends one for the596/// paths of each batch it is about to read, and for the tree a rescan597/// reads, and reads only once the step answers with598/// [`TreeFileOutput::Released`], after those writes: the shell never waits599/// on the tree in a turn of its own.600#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]601pub struct Closed {602    /// The paths, or directories, that settled.603    pub under: Vec<TreeFilePath>,604    /// What the shell reads once they are released.605    pub cause: ClosedCause,606}607608/// Why the shell sent a [`Closed`]: what it reads once the tree's609/// writes are released.610#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]611pub enum ClosedCause {612    /// A batch of changed paths, `under` itself, which it reads.613    Changed,614    /// The watcher lost events: it rescans the whole tree.615    Lost,616    /// The watcher lost events under this directory: it rescans it.617    LostUnder(TreeFilePath),618    /// `under` is empty: every stat of the last rescan was handled before619    /// this, so the rescan is done.620    Rescanned,621}622623/// The tree actor's events, generated by its sml table: its dispatch624/// and journal type (discussion:owner/286 and discussion:owner/341).625///626/// The rules below rely on these obligations of the shell (`M1.daemon`):627/// - Only syncable paths arrive: never `.lvcs/`, never-sync paths, or628///   symbolic links. The tree never filters.629/// - Each `Fs` event carries what the shell read, its hash, and the630///   `Origin` the shell built (discussion:owner/75). Each `DocOutput::Rendered` of a631///   tree file's document arrives, in the order the document emitted632///   them, as a `Doc` event with the rendered bytes' hash, or for a633///   protected path as what `protect::gate` decides (discussion:owner/122): the634///   render, a `Doc` render at the path's approved heads carrying the635///   gated render's `after`, or a `Held` carrying it. When approved heads636///   move, the shell re-gates the path's latest render, and that `Doc` or637///   `Held` carries no `after`, since the render's `after` already arrived.638///   Each render's `after` arrives exactly once, on a `Doc` or a `Held`, and639///   each `DiskEdit` reaches the document in the order the tree emitted640///   them.641/// - A file's writes and removals run in the order the tree emitted642///   them. Each first compares the file's hash with its `expect` and is643///   answered by exactly one `Written` or, when it is refused, one `Fs`644///   event with `refused` set to its heads (discussion:owner/75), or, for a645///   `WriteFile` on Windows that another process holds the file open646///   against, one `WriteHeld` carrying the write.647/// - Each `Wake` is answered by one `Tick` for its path, carrying a time648///   no earlier than its `at_ms`.649/// - A write's `Written` arrives before any `Fs` event the shell reads after650///   that write lands (discussion:owner/78).651/// - Each incarnation's first event is `Probed`, then `IndexLoaded` with652///   the tree's index (discussion:owner/433), then one `Statted` per indexed path653///   and per other synced file on disk, before any document re-renders to654///   the tree. After lost events the shell stats the tree again. A655///   `Read` is answered with one `Fs` event carrying the file's stat.656/// - A `Loaded` carries the SHA-256 of the bytes a hook read from the file657///   (discussion:owner/117).658///659/// The document actor (`M1.doc`) answers each `DiskEdit` with exactly one660/// `Rendered` whose `after` is its stamp, whether the edit committed,661/// changed nothing, or faulted (discussion:owner/78).662///663/// The rules the tree keeps per path are its `FileSync` table's664/// (discussion:owner/433, the `machine` module): each path's index entry is the665/// version the tree last rendered or saved there, what it puts on disk,666/// the stat the tree's own last write landed with, and a write in flight;667/// a save names the entry's heads as its base, and a file with no entry668/// is saved with none; a stat equal to the entry's own write is the669/// tree's own bytes, never read; a read holding neither the entry's nor670/// the pending write's bytes is an edit; writes and removals expect what671/// the last one puts on disk (discussion:owner/75), are staged while a local write672/// settles (discussion:owner/131), and are retried while another process holds673/// the file (Windows, discussion:owner/252); a save refused stale keeps the file's674/// bytes until the disk holds the version the refusal showed or a render675/// equals the disk (discussion:owner/343 and discussion:owner/389).676///677/// Its events, each the payload type its variant is named for:678/// - [`FsChanged`]: The shell read a file.679/// - [`WriteDone`]: The shell finished a write or removal.680/// - [`DocRendered`]: A document rendered the file.681/// - [`IndexLoaded`]: The shell read the tree's index.682/// - [`Statted`]: The shell stat'ed a file.683/// - [`Intended`]: A peer declared it is about to change a file.684/// - [`IntentEnded`]: A peer's intent ended.685/// - [`Loaded`]: A hook read a file.686/// - [`Locate`]: A hook asks which version of a file its tool edits.687/// - [`Held`]: The protected-path gate held a render.688/// - [`SaveRefused`]: The daemon refused a save of a file.689/// - [`SaveLost`]: No document took a save of a file.690/// - [`WriteHeld`]: Another process held a file open against a write (Windows).691/// - [`Tick`]: A wake the tree asked for came.692/// - [`Writing`]: A local write is under way at some paths.693/// - [`Moved`]: A file moved under the shell's read.694/// - [`Renamed`]: A rename on disk left one path for another.695/// - [`MoveDone`]: The namespace answered a rename's move.696/// - [`Closed`]: The writes under way at or under a path ended.697pub use machine::{TreeFileSyncEvents, UNCHANGED_GUARD};698699/// Outputs of the tree actor.700#[derive(Debug, Clone, PartialEq, Eq)]701pub enum TreeFileOutput {702    /// Write `content` to `path` with the executable bit; the shell answers703    /// with [`WriteDone`]. `expect` is the content hash the tree believes704    /// the file has when the shell runs this write (`None`: no file). The705    /// shell writes only if the file on disk has that hash; otherwise it706    /// leaves the file alone and answers with an [`FsChanged`] reporting707    /// what it found, `refused` set to `heads`, instead of [`WriteDone`], so708    /// the tree never overwrites a save it hasn't seen (discussion:owner/75).709    WriteFile {710        /// The file to write.711        path: TreeFilePath,712        /// The bytes to write.713        content: Vec<u8>,714        /// SHA-256 of `content`.715        hash: ContentHash,716        /// The executable bit to set.717        executable: bool,718        /// The heads of the document version written.719        heads: Vec<crate::ChangeId>,720        /// The content hash the file must have for the write to run;721        /// `None`: no file.722        expect: Option<ContentHash>,723    },724    /// Remove `path`. `expect` works as for `WriteFile`: when the file has725    /// hash `expect`, or for `None` when there is no file, the shell removes726    /// it (nothing to do when absent) and answers with [`WriteDone`] with no727    /// hash; otherwise it leaves the file alone and answers with an728    /// [`FsChanged`], `refused` set to `heads`, so a removal never deletes a729    /// save the tree hasn't seen (discussion:owner/75).730    RemoveFile {731        /// The file to remove.732        path: TreeFilePath,733        /// The heads of the document version removed, whose body is734        /// deleted.735        heads: Vec<crate::ChangeId>,736        /// The content hash the file must have for the removal to run;737        /// `None`: no file.738        expect: Option<ContentHash>,739    },740    /// A rename on disk ([`Renamed`]): the shell moves `from` to `to` in the741    /// namespace (`MovePath` to `.lvcs/tree`) as `origin`'s writer, so the742    /// file keeps its id and document, and answers with [`MoveDone`].743    MovePath {744        /// The path it left.745        from: TreeFilePath,746        /// Where it is now.747        to: TreeFilePath,748        /// The disk's author.749        origin: crate::Origin,750        /// Every file's old and new paths, whose writes the grant must751        /// cover, as `lvcs mv` checks each.752        files: Vec<TreeFilePath>,753    },754    /// The file at `path` is gone from disk, not as an echo (history row755    /// 457): the shell removes the path from the namespace (`RemovePath` to756    /// `.lvcs/tree`) as `origin`'s writer, and answers with a757    /// [`DocRendered`] with `removed` set and `stamp` as its `after`, or,758    /// when the namespace refused, the file document's render with `stamp`.759    RemovePath {760        /// The file removed.761        path: TreeFilePath,762        /// Who removed it, and when.763        origin: Origin,764        /// The save's stamp, which the answering render carries.765        stamp: u64,766        /// The version it was made from, chosen as a text save's base: the767        /// intent's heads, else the entry's; `None` when the path showed768        /// none. A removal of a version the file has since moved past is769        /// refused stale (discussion:owner/296).770        base: Option<Vec<crate::ChangeId>>,771    },772    /// A disk change that is not an echo, for the document at `path`. Its773    /// origin's signer is the peer whose intent it answers (row 440), whose774    /// author, grant, and device the shell binds; otherwise the host's.775    DiskEdit {776        /// The document's path.777        path: TreeFilePath,778        /// The change.779        edit: DiskEdit,780    },781    /// The answer to [`Locate`] `req`: the version of the file at `path` a782    /// hook's tool edits (discussion:owner/117), the loaded heads or the newest783    /// disk base's, or `None` when the tree knows neither.784    Located {785        /// The [`Locate`] request answered.786        req: RequestId,787        /// The file located.788        path: TreeFilePath,789        /// The version the tool edits; `None` when the tree knows none.790        heads: Option<Vec<crate::ChangeId>>,791    },792    /// Answer with a [`Tick`] for `path` once the shell's clock reaches793    /// `at_ms`: the time to write a held file again.794    Wake {795        /// The held file.796        path: TreeFilePath,797        /// When to tick, Unix milliseconds.798        at_ms: i64,799    },800    /// The tree stopped writing `path` after `HELD_DEADLINE_MS`: another801    /// process kept it open, so the file on disk is older than its802    /// document at `heads` (`write_held`).803    HeldReport {804        /// The held file.805        path: TreeFilePath,806        /// The heads of the version the tree could not write.807        heads: Vec<crate::ChangeId>,808    },809    /// A path a [`TreeFileOutput::HeldReport`] named is no longer behind its810    /// document: a write of it landed, or the disk already holds its811    /// render.812    HeldCleared {813        /// The file.814        path: TreeFilePath,815    },816    /// The file keeps a refused save's bytes (discussion:owner/343): the tree817    /// writes no render of it, so it holds back a change `main` lacks, until818    /// a save of it is answered or a render holds exactly those bytes819    /// (owner/12).820    Kept {821        /// The file.822        path: TreeFilePath,823        /// The refused save's writer, when the hold is one the index824        /// recorded before this opening ([`IndexEntry::held_by`]): the825        /// refusal that would name it was told to a daemon that has since826        /// stopped (orchestrator/57). `None` for a save refused now, whose827        /// refusal names its writer.828        by: Option<PeerKey>,829    },830    /// A path a [`TreeFileOutput::Kept`] named keeps nothing back any more.831    KeptCleared {832        /// The file.833        path: TreeFilePath,834    },835    /// Put `entry` in the index for `path` (discussion:owner/433), after the step836    /// that emitted it is journaled (discussion:owner/429) and before any write837    /// the same step emitted after it.838    IndexPut {839        /// The path.840        path: TreeFilePath,841        /// Its entry.842        entry: IndexEntry,843    },844    /// Remove `path` from the index (discussion:owner/433).845    IndexRemove {846        /// The path.847        path: TreeFilePath,848    },849    /// Read `path` again, now: a state of the path asks. The shell answers850    /// with [`FsChanged`].851    Read {852        /// The path.853        path: TreeFilePath,854    },855    /// The pending rename bound was exceeded; the oldest pair falls back to856    /// ordinary reads. The shell reports this after the event is journaled,857    /// so replay does not repeat the error log (f-break/6).858    RenameOverflowed {859        /// The fixed maximum pending pairs, never a path or peer id.860        limit: usize,861    },862    /// The oldest delayed-refusal identity was evicted; an effect logs the863    /// loss after the event is journaled, without a path or peer id.864    RefusedBodyOverflowed {865        /// The fixed maximum identities held by the tree.866        limit: usize,867    },868    /// A path's oldest delayed-refusal identity was evicted for its newest869    /// (unproven-base/1): a bounded degrade, logged as a warning, never the870    /// tree's overflow.871    RefusedBodyEvicted {872        /// The fixed maximum identities held for one path.873        limit: usize,874    },875    /// A stat of `path` differed from the entry's own write (discussion:owner/433):876    /// bytes no event told of, which a writer may still be writing, so the877    /// shell reads them once they settle, as a change's, and answers with878    /// [`FsChanged`].879    Unseen {880        /// The path.881        path: TreeFilePath,882    },883    /// The writes a [`Closed`] released are out, before this: the shell884    /// reads what `cause` says.885    Released {886        /// The `Closed`'s paths.887        under: Vec<TreeFilePath>,888        /// The `Closed`'s cause.889        cause: ClosedCause,890    },891}