From 160a8a855c5f79a030677efcead75b9cea5ec57f Mon Sep 17 00:00:00 2001 From: Simon Klee Date: Wed, 18 Nov 2026 21:04:38 +0100 Subject: [PATCH] docs(cli-rs): state the invariants behind asynchronous reads Replace old model and deviation labels with the actual conditions: a cursor can become stale, a read can be overtaken by an event, and an unlocked writer can change the file being replaced. Remove the same tracking references from comments on UI behavior. --- packages/cli-rs/crates/cli/src/contain.rs | 1 - packages/cli-rs/crates/cli/src/prompt/mod.rs | 3 +-- packages/cli-rs/crates/local/src/jsonl.rs | 11 +++-------- packages/cli-rs/crates/mermaid/src/plugin.rs | 2 -- packages/cli-rs/crates/mini/src/replay.rs | 7 +++---- packages/cli-rs/crates/mini/src/scrollback.rs | 5 ----- packages/cli-rs/crates/mini/src/stderr.rs | 7 ++----- packages/cli-rs/crates/service/src/stop.rs | 3 +-- packages/cli-rs/crates/store/src/forms.rs | 5 ++--- packages/cli-rs/crates/store/src/messages.rs | 11 ++++------- packages/cli-rs/crates/store/src/permissions.rs | 4 ++-- packages/cli-rs/crates/store/src/projects.rs | 4 ++-- packages/cli-rs/crates/store/src/shells.rs | 3 +-- packages/cli-rs/crates/store/src/state.rs | 12 ++++-------- packages/cli-rs/crates/store/tests/model.rs | 7 ++----- packages/cli-rs/crates/ui/src/code.rs | 8 ++------ packages/cli-rs/crates/ui/src/diff.rs | 6 ++---- packages/cli-rs/crates/ui/src/keymap/mod.rs | 6 ++---- packages/cli-rs/crates/ui/tests/all/content.rs | 3 --- 19 files changed, 33 insertions(+), 75 deletions(-) diff --git a/packages/cli-rs/crates/cli/src/contain.rs b/packages/cli-rs/crates/cli/src/contain.rs index 08049723490..7bd404b6ff2 100644 --- a/packages/cli-rs/crates/cli/src/contain.rs +++ b/packages/cli-rs/crates/cli/src/contain.rs @@ -666,7 +666,6 @@ mod sys { /// handler was set, or the console closing. const CONTROL_C_EXIT: u32 = 0xC000_013A; - /// The parent is this binary again: a small binary of its own was not built (synthesis 4.5 prices both). pub fn supervise(raw: Vec, restart: Restart) -> Result, i32> { let Ok(exe) = std::env::current_exe() else { return Ok(raw) }; // Before any client starts: Ctrl+C reaches every process on the console, and the client owns it; the end of diff --git a/packages/cli-rs/crates/cli/src/prompt/mod.rs b/packages/cli-rs/crates/cli/src/prompt/mod.rs index 66bf4d21fd0..bff58a14e27 100644 --- a/packages/cli-rs/crates/cli/src/prompt/mod.rs +++ b/packages/cli-rs/crates/cli/src/prompt/mod.rs @@ -54,8 +54,7 @@ pub enum Output { type Validate<'a, V> = Box Option + 'a>; -/// A caller's text (session titles, provider names, server messages, URLs) without escape sequences or control -/// characters, before the prompt styles it. Clack writes it raw (`parity/deviations/O89-terminal-text.md`). +/// Strips terminal escape sequences and controls from untrusted text before styling it. fn clean(text: impl Into) -> String { let text: String = text.into(); opencode_ui::terminal_text(&text).into_owned() diff --git a/packages/cli-rs/crates/local/src/jsonl.rs b/packages/cli-rs/crates/local/src/jsonl.rs index 2e345f4e5b1..f8c9dadec45 100644 --- a/packages/cli-rs/crates/local/src/jsonl.rs +++ b/packages/cli-rs/crates/local/src/jsonl.rs @@ -166,14 +166,9 @@ fn with_lock(state: &Path, file: &Path, f: impl FnOnce() -> io::Result) -> // How often [`rewrite`] reads again after another client changed the file under it. const REWRITE_ATTEMPTS: usize = 5; -// Rewrites `file` atomically with `change(text)` when that gives a new text. The TypeScript TUI writes -// without the lock (deviation O89-jsonl-writes), so the replace happens only while the file still holds -// what was read. Otherwise the change is made again against a new read. Contents, not metadata: a -// TypeScript rewrite truncates in place and may keep the length, and on Windows the modification time -// can stay within one clock tick. The new text is synced before the rename, so a crash leaves the old -// file or the new one. -// A client that appends to the old file between the check and the rename writes to the open old file; -// the lines it gained are carried over to the end of the new one. +// Rewrites atomically from the current bytes, retrying if they changed during the edit. An unlocked writer can +// preserve both size and timestamp. Sync before renaming; a concurrent append through the old inode can still be +// lost between the final check and rename. fn rewrite(file: &Path, mut change: impl FnMut(&str) -> Option) -> io::Result<()> { for _ in 0..REWRITE_ATTEMPTS { let mut old = match fs::File::open(file) { diff --git a/packages/cli-rs/crates/mermaid/src/plugin.rs b/packages/cli-rs/crates/mermaid/src/plugin.rs index 0e184e1f525..72cb207e260 100644 --- a/packages/cli-rs/crates/mermaid/src/plugin.rs +++ b/packages/cli-rs/crates/mermaid/src/plugin.rs @@ -77,8 +77,6 @@ mod tests { use opentui::prelude::*; use opentui::testing::TestApp; - // Expected (bigboi notes): the kind each diagram showed goes once the host frees its block, so N diagrams drawn - // and removed leave nothing. #[test] fn removed_diagrams_leave_no_kinds() { let app = TestApp::new(80, 200); diff --git a/packages/cli-rs/crates/mini/src/replay.rs b/packages/cli-rs/crates/mini/src/replay.rs index cf3dcedb6a3..5666e60e38a 100644 --- a/packages/cli-rs/crates/mini/src/replay.rs +++ b/packages/cli-rs/crates/mini/src/replay.rs @@ -28,8 +28,7 @@ pub const DEFAULT_REPLAY_LIMIT: u32 = 200; /// `LOCAL_REPLAY_ROW_LIMIT`: rows printed only locally (errors, prompts in flight) that a resize replays. pub const LOCAL_ROW_LIMIT: usize = 100; pub const RESIZE_DELAY: Duration = Duration::from_millis(250); -/// The events a resize replay holds while it lists. TS holds any number -/// (`parity/deviations/O92-mini-relist-overflow.md`). +/// Maximum events buffered during a resize replay. pub const RELIST_LIMIT: usize = 4096; /// A part of a message whose text arrives in pieces (`FragmentRef`). @@ -507,8 +506,8 @@ impl Transcript { if commit.message_id.as_ref().is_some_and(|message| self.message_ids.contains(message)) { return None; } - // A prompt the list did not have yet counts as shown, so it does not print again once listed. TS does not - // record it (`parity/deviations/O89-mini-restored-prompt.md`). + // Mark the restored prompt as shown even when the snapshot lacks it, so a later listing cannot print it + // twice. if commit.kind == EntryKind::User && let Some(message) = &commit.message_id { diff --git a/packages/cli-rs/crates/mini/src/scrollback.rs b/packages/cli-rs/crates/mini/src/scrollback.rs index 9dce980136c..e67f518f6ab 100644 --- a/packages/cli-rs/crates/mini/src/scrollback.rs +++ b/packages/cli-rs/crates/mini/src/scrollback.rs @@ -1169,8 +1169,6 @@ mod tests { assert_eq!(capture.cell(0, 2).unwrap().fg, entry_color(&commit, &theme)); } - /// A table is borderless columns two cells apart in both modes, as TS's top-level Markdown draws it. The `-:` column - /// is right-aligned, where TS on Core 0.8.4 left-aligns it (`parity/deviations/OT2112-table-alignment.md`). #[test] fn tables_are_borderless_columns() { let commit = assistant("", Phase::Final); @@ -1191,9 +1189,6 @@ mod tests { } } - /// Mini hides the tildes of `~~x~~` and strikes the text through, in every theme and body: native code strikes - /// `markup.strikethrough` unless a style turns the bit off, which a Rust `Style` cannot. TS mini on Core 0.8.4 - /// draws the text plain (`parity/deviations/OT2079-strikethrough.md`). #[test] fn strikethrough_text_is_struck() { let full = crate::theme::resolve(&crate::theme::ThemeInput { diff --git a/packages/cli-rs/crates/mini/src/stderr.rs b/packages/cli-rs/crates/mini/src/stderr.rs index e260903f434..864a30e5b6e 100644 --- a/packages/cli-rs/crates/mini/src/stderr.rs +++ b/packages/cli-rs/crates/mini/src/stderr.rs @@ -1,8 +1,5 @@ -//! Stderr while the split footer is up. A `--print-logs` record or any other write to stderr would draw over the -//! footer, so each line becomes a row of the scrollback above it instead. TS mini captures only stdout -//! (`externalOutputMode: "capture-stdout"`); see `parity/deviations/O89-mini-stderr.md`. -//! -//! Only this process's writes are captured: a standalone server started before mini keeps the real stderr. +//! Routes stderr to scrollback while the split footer owns the terminal. A server started before mini keeps its own +//! stderr. /// One line written to stderr, without its line ending. The app's message handlers receive it. pub struct Line(pub String); diff --git a/packages/cli-rs/crates/service/src/stop.rs b/packages/cli-rs/crates/service/src/stop.rs index fa3767df0f6..aad0382815e 100644 --- a/packages/cli-rs/crates/service/src/stop.rs +++ b/packages/cli-rs/crates/service/src/stop.rs @@ -44,8 +44,7 @@ pub enum Error { NotTheServer { pid: u32, file: PathBuf }, } -/// Stops the service registered in `file`, if any. A live pid that is not that service's process -/// (a stale registration whose pid was reused) is never signalled (deviation O89-service-stop-pid). +/// Stops the registered service. Never signal a PID that has been reused by another process. pub async fn stop(transport: Arc, file: &Path, pty: Pty, poll: Poll) -> Result<(), Error> { let info = registration::read(file); if let Some(info) = &info diff --git a/packages/cli-rs/crates/store/src/forms.rs b/packages/cli-rs/crates/store/src/forms.rs index df41fe4d0b4..2771daf2e4f 100644 --- a/packages/cli-rs/crates/store/src/forms.rs +++ b/packages/cli-rs/crates/store/src/forms.rs @@ -118,9 +118,8 @@ impl State { } impl Data { - /// Reads pending forms once per invalidation: a session's, or the global forms of a location - /// (the default one for `None`). Forms created or settled while the read was in flight win over - /// the snapshot (model M1, deviation O89-list-snapshots). + /// Reads pending forms for a session or location. Forms created or settled during the read take precedence over + /// its snapshot. pub fn form_sync(&self, owner: &str, location: Option<&Location>) -> Task<()> { let location = location.cloned().unwrap_or_else(|| self.read(|state| state.default_location().clone())); let owner = owner.to_owned(); diff --git a/packages/cli-rs/crates/store/src/messages.rs b/packages/cli-rs/crates/store/src/messages.rs index 8a6a5bf2bd4..ff52ff84ff3 100644 --- a/packages/cli-rs/crates/store/src/messages.rs +++ b/packages/cli-rs/crates/store/src/messages.rs @@ -958,9 +958,8 @@ fn edit_session(event: &V2Event) -> Option<&SessionID> { } impl Data { - /// Reads the newest page of a transcript once per invalidation (`message.sync`). What events - /// created or edited while the read was in flight is merged by `durable.seq` (models M2, - /// deviation O89-transcript-refresh, see [`State::publish_head`]). + /// Reads the newest transcript page once per invalidation. Merge concurrent events by `durable.seq`; see + /// [`State::publish_head`]. pub fn message_sync(&self, session: &SessionID) -> Task<()> { let key = format!("session.message:{}", session.0); let begin = session.clone(); @@ -1147,10 +1146,8 @@ impl Data { } } -/// Fetches older pages and publishes them once; false when cancelled before publishing. A latest-page -/// refresh that replaced the cursor meanwhile, or a window that ended (models M2 rule 5), makes the -/// pages stale: stitching them onto the new list would leave a gap, so the load starts again from -/// the current cursor (deviation O89-older-page). +/// Publishes older pages once. If a refresh changes the cursor, restart from the new cursor to avoid a gap. Returns +/// false on cancellation before publication. async fn load_pages( data: &Data, session: &SessionID, diff --git a/packages/cli-rs/crates/store/src/permissions.rs b/packages/cli-rs/crates/store/src/permissions.rs index 072e5600611..90c4de01002 100644 --- a/packages/cli-rs/crates/store/src/permissions.rs +++ b/packages/cli-rs/crates/store/src/permissions.rs @@ -53,8 +53,8 @@ impl State { } impl Data { - /// Reads pending permissions once per invalidation (`permission.sync`). Requests asked or - /// settled while the read was in flight win over the snapshot (deviation O89-list-snapshots). + /// Reads pending permissions once per invalidation. Requests opened or settled during the read take precedence + /// over its snapshot. pub fn permission_sync(&self, session: &SessionID) -> Task<()> { let (fetched, again) = (session.clone(), session.clone()); self.overlay_sync( diff --git a/packages/cli-rs/crates/store/src/projects.rs b/packages/cli-rs/crates/store/src/projects.rs index d0f91799c5a..65779a55567 100644 --- a/packages/cli-rs/crates/store/src/projects.rs +++ b/packages/cli-rs/crates/store/src/projects.rs @@ -100,8 +100,8 @@ pub fn adopt(project: &str, directory: &str, event: &WorktreeResolvedData) -> Op if key != parent && !key.starts_with(&format!("{parent}/")) { return None; } - // The segments after the root's. TS slices `directory.slice(root.length + 1)`, which is wrong when - // lowercasing changed a length (deviation O89-adopt-case-fold). + // Case folding can change byte length, so count matching path segments rather than slicing at the root's byte + // length. let subpath = (key != parent).then(|| directory.split('/').skip(root.split('/').count()).collect::>().join("/")); Some((event.project_id.0.clone(), subpath)) diff --git a/packages/cli-rs/crates/store/src/shells.rs b/packages/cli-rs/crates/store/src/shells.rs index 77066d5c0bc..3319937c5b2 100644 --- a/packages/cli-rs/crates/store/src/shells.rs +++ b/packages/cli-rs/crates/store/src/shells.rs @@ -122,8 +122,7 @@ impl Data { self.catalog_sync(Catalog::Shell, location) } - /// The `Catalog::Shell` read. A shell created or exited while it is in flight overrides the list it returns - /// (deviation O92-shell-list), so the list never loses a new shell or brings back an exited one. + /// Shell creation and exit events received during a list read take precedence over the snapshot. pub(crate) fn shell_read(&self, location: Location) -> Task<()> { let begin = location.clone(); self.sync_start( diff --git a/packages/cli-rs/crates/store/src/state.rs b/packages/cli-rs/crates/store/src/state.rs index 245c036d6f7..a0ff4714bc7 100644 --- a/packages/cli-rs/crates/store/src/state.rs +++ b/packages/cli-rs/crates/store/src/state.rs @@ -127,10 +127,8 @@ pub struct State { /// Maximum changes retained by one in-flight list read. pub(crate) const OVERLAY_LIMIT: usize = 1024; -/// What overtook one list read (model M1, deviation O89-list-snapshots): the items events added -/// (`Some`) or settled (`None`) while it was in flight, by ID in arrival order. Only the read whose -/// ticket it carries publishes. More than [`OVERLAY_LIMIT`] changes overflow it: the read then -/// publishes nothing and reads again, so the bound costs a read, never an item. +/// Changes that overtake a list read, keyed by ID in arrival order. Only the current ticket can publish. Beyond +/// [`OVERLAY_LIMIT`], retry instead of losing an item. #[derive(Debug, Clone)] pub(crate) struct Overlay { ticket: u64, @@ -648,10 +646,8 @@ impl Data { task } - /// A list read under an [`Overlay`] (model M1, deviation O89-list-snapshots), registered in `reads` under - /// `read`. `fetch` reads the list and `publish` stores it with the overlay applied, unless a newer read - /// replaced this one or `session` was deleted after it began. An overflowed overlay publishes nothing: `key` - /// is invalidated and `again` reads again. + /// Fetches a list and applies its overlay before publishing. Discard superseded reads and reads for deleted + /// sessions. An overflow invalidates the key and schedules another read. #[allow(clippy::too_many_arguments)] pub(crate) fn overlay_sync( &self, diff --git a/packages/cli-rs/crates/store/tests/model.rs b/packages/cli-rs/crates/store/tests/model.rs index e690dbccca1..d399b686b48 100644 --- a/packages/cli-rs/crates/store/tests/model.rs +++ b/packages/cli-rs/crates/store/tests/model.rs @@ -1372,8 +1372,7 @@ fn the_checker_catches_wrong_clients() { assert!(missed.is_empty(), "the checker misses {missed:?}"); } -/// The shrinker keeps the class of the failure it started from: a sequence that first fails on transcript order (O10) -/// and also on permissions (the `Reversed` mutant) must not shrink to the shorter permission failure. +/// Shrinking a transcript-order failure must not select a shorter sequence that fails only on permissions. #[test] fn the_shrinker_keeps_the_failure_class() { let ops = [ @@ -1526,9 +1525,7 @@ const KNOWN: &[(&str, &str, &[Op])] = &[ ]; const OPEN: &[(&str, &str, &[Op])] = &[ - // O10: the stream lags behind a head page that already holds newer rows. A `step.started` delivered after the - // read published has no page row with a known `durable.seq` to compare with, so it is appended after newer rows. - // TS and the old `message_live` do the same (models-6 report). + // A delayed `step.started` can arrive after a newer head page that contains no comparable `durable.seq`. ( "late step after the newest page", "order ses_0", diff --git a/packages/cli-rs/crates/ui/src/code.rs b/packages/cli-rs/crates/ui/src/code.rs index 1abbe0e3ddf..05a2dc4f3d5 100644 --- a/packages/cli-rs/crates/ui/src/code.rs +++ b/packages/cli-rs/crates/ui/src/code.rs @@ -110,12 +110,8 @@ pub fn syntax_theme(theme: &Theme) -> SyntaxTheme { styles } -/// The paste chip's text: the page color, dark in dark mode and light in light mode (#62930). A transparent page (the -/// system theme) still holds the terminal's background in its channels, so the chip takes that. A transparent page -/// without one takes the end of the neutral scale that reads better on the chip. -/// -/// TypeScript takes the selected-row text instead, which is the light foreground on the system theme in dark mode -/// (`parity/deviations/O89-paste-chip-contrast.md`). +/// Paste chips use the page color for contrast. For transparent pages, use the terminal background if known or a +/// contrasting neutral shade. fn paste_text(theme: &Theme) -> Color { let page = theme.background.base; if page.a == 255 { diff --git a/packages/cli-rs/crates/ui/src/diff.rs b/packages/cli-rs/crates/ui/src/diff.rs index 7a8371be341..116acd1385e 100644 --- a/packages/cli-rs/crates/ui/src/diff.rs +++ b/packages/cli-rs/crates/ui/src/diff.rs @@ -308,10 +308,8 @@ pub fn added_lines(patch: &str) -> Option { (added == count).then_some(count) } -/// `VirtualAddedPatch`: an added file over 3,000 lines in chunks of 128 rows, unwrapped so each chunk is exactly its -/// rows tall. Only the chunks [`Chunked::show`] puts in view are mounted; the others are blank rows of their height. -/// Each chunk is highlighted on its own (deviation `H06-chunked-diff-highlights`). A theme restyles the mounted chunks -/// in place and the ones mounted later take it. +/// Virtualizes added files over 3,000 lines in unwrapped 128-row chunks. Unmounted chunks reserve their full height; +/// mounted chunks highlight independently. pub struct Chunked { root: View, app: App, diff --git a/packages/cli-rs/crates/ui/src/keymap/mod.rs b/packages/cli-rs/crates/ui/src/keymap/mod.rs index c32a9ce9bf5..17a05f8d58d 100644 --- a/packages/cli-rs/crates/ui/src/keymap/mod.rs +++ b/packages/cli-rs/crates/ui/src/keymap/mod.rs @@ -430,10 +430,8 @@ impl TuiKeymap { &self.keymap } - /// The key sequences a layer's binding `key` binds, as the keymap expands it when the layer registers: a comma - /// separates bindings, none of them empty, and each alias of [`ALIASES`] between the boundaries the engine uses - /// (`+`, `,`, `<`, `>`, whitespace) is its key. [`Keymap::parse_key_sequence`] alone runs neither expansion, so a - /// check of what a binding takes must judge these (review carbon new-3). + /// Expands comma-separated bindings and key aliases at token boundaries before parsing the sequences, just as + /// layer registration does. pub fn parse_binding(&self, key: &str) -> Result>, String> { let bindings: Vec<&str> = match key.contains(',') { true => key.split(',').map(str::trim).collect(), diff --git a/packages/cli-rs/crates/ui/tests/all/content.rs b/packages/cli-rs/crates/ui/tests/all/content.rs index d8fcd09eddb..76dd1000bbf 100644 --- a/packages/cli-rs/crates/ui/tests/all/content.rs +++ b/packages/cli-rs/crates/ui/tests/all/content.rs @@ -45,9 +45,6 @@ fn syntax_theme_matches_generate_syntax() { } } -/// The paste chip keeps the page color on its warning background under a transparent page too -/// (`parity/deviations/O89-paste-chip-contrast.md`): the terminal's background when the system theme read one, else the -/// neutral end that reads better on the chip. TypeScript draws the light foreground on the dark-mode system theme. #[test] fn paste_chip_text_is_the_page_color_on_a_transparent_page() { let tokyo = "#1a1b26 #f7768e #9ece6a #e0af68 #7aa2f7 #ad8ee6 #449dab #a9b1d6 #414868 #ff7a93 #b9f27c #ff9e64 #7da6ff #bb9af7 #0db9d7 #c0caf5";