docs/generated/contracts.mdgenerated from code
Reference · 26 min read
tree
Contracts: tree.
Read as
Source: crates/lvcs-doc/src/tree_file/mod.rs.
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}