iris/ai-app
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prune commentary and stale Rust port notes

Browse Source
This commit is contained in:
iris committed 2026-09-10 00:44:13 -04:00
1 parent 5428cd75c9
commit 25370731d0
193 files changed
+693 -16219
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

server/src/session/transcript.rs
-157
View File
@@ -1,11 +1,3 @@
//! Append-only JSONL event log, one per session, with monotonically
//! increasing sequence numbers -- the phone's resume cursor.
//!
//! One line per event: `{"seq":N,"ts":...,"type":...,...}`. The writer
//! assigns sequence numbers; readers replay everything after a cursor.
//! Reopening an existing file continues the numbering, which is what makes
//! a backend restart invisible to a phone holding a cursor.
use std::fs::{File, OpenOptions};
use std::io::Write;
use std::ops::Range;
@@ -17,9 +9,6 @@ use serde::Deserialize;
use super::driver::{Event, SessionStatus, context_after};
// `SeqEvent` moved to `event-model` on 2026-09-04 along with the rest of the
// event model, so `client-core` can read the same wire shape; re-exported
// here since every caller in this crate reaches it through this module.
pub use event_model::SeqEvent;
pub struct Transcript {
@@ -31,8 +20,6 @@ pub struct Transcript {
}
impl Transcript {
/// Opens (or creates) the log at `path`, continuing the sequence from
/// the last line if one exists.
pub fn open(path: &Path) -> Result<Self> {
// One pass for all three answers. They are wanted at the same moment
// by the same caller, and reading the file again for each doubled the
@@ -43,8 +30,6 @@ impl Transcript {
Event::Status { state } => Some(state),
_ => None,
});
// Owner-only: a transcript is the whole conversation, including
// whatever the session read, wrote, or was told.
let file = OpenOptions::new()
.create(true)
.append(true)
@@ -56,17 +41,12 @@ impl Transcript {
next_seq: last_seq + 1,
last_status,
last_activity: existing.last().map(|entry| entry.ts),
// Folded rather than read off the newest usage entry: a clear or
// a compaction after it is what the answer is, and those events
// carry no usage of their own.
context_tokens: existing
.iter()
.fold(None, |current, entry| context_after(current, &entry.event)),
})
}
/// The state the session was last reported to be in, as of opening.
///
/// Read from the file rather than assumed, because a server that has just
/// restarted has been told nothing. Assuming idle claimed a session was
/// waiting for you when it had exited hours earlier.
@@ -76,14 +56,6 @@ impl Transcript {
self.last_status
}
/// When this session last did anything, as of opening.
///
/// Read from the file for the reason [`Transcript::last_status`] is, and it
/// is the same mistake in the other direction: taking the clock instead
/// said every session it relaunched had been active this second. On the
/// phone that is every row reading "just now" and the list -- sorted by
/// this -- in an order that means nothing.
///
/// `None` for a transcript with no lines, which is a session that genuinely
/// has not done anything. Its caller answers with when the session was
/// created, not with the clock.
@@ -91,8 +63,6 @@ impl Transcript {
self.last_activity
}
/// How much context the session was holding, as of opening.
///
/// `None` for a transcript nothing has been measured in. That is not zero:
/// a server that has just restarted has been told nothing, and answering
/// zero would draw an empty context for a conversation that may be nearly
@@ -120,16 +90,6 @@ impl Transcript {
}
}
/// A window of the transcript ending just before `before`, newest-biased.
///
/// The screen opens on the end of a conversation, and the end is all it can
/// show at once. Replaying the whole file to get there costs one network frame
/// per event -- on an 863-event import that was several seconds of messages
/// arriving oldest-first, which reads as the app loading top-down.
///
/// `before` pages backwards for history somebody actually scrolls to. Only the
/// window is parsed; see [`Indexed`] for why that is the whole cost.
///
/// `after` is a floor: nothing at or below it is returned, and the page stops
/// there rather than at `limit`. A phone holding a cached run passes the end of
/// what it already has, so the page is exactly the gap and never overlaps its
@@ -153,13 +113,7 @@ pub fn read_window(
Some(after) => indexed.first_at_or_after(after.saturating_add(1))?,
None => 0,
};
// A floor above the window is an empty page, not a walk backwards past it.
let start = start.min(end);
// Coalescing counts *rows*, not events, and would misread the newest
// window: a message still streaming there would fold to one event whose seq
// is its first delta, and the phone resumes its live stream from the newest
// seq it applied -- so the deltas the coalesced event hid would replay and
// double. Only settled history (`before` set) is safe.
if coalesce && before.is_some() {
indexed.parse_coalesced(start, end, limit)
} else {
@@ -167,37 +121,18 @@ pub fn read_window(
}
}
/// How far behind a reconnecting subscriber can be and still be handed the
/// backlog one event at a time.
///
/// Past this it is served better by rebuilding from the newest window. The
/// events are the same either way; what differs is that one arrives as a single
/// window and the other as thousands of frames a screen renders one by one. Set
/// well above a screenful so an ordinary blip still streams continuously.
pub const CATCH_UP_LIMIT: usize = 200;
/// What a subscriber asking for "everything after my cursor" gets back.
///
/// Two answers rather than one list, because they mean different things to the
/// screen holding the cursor: one continues what it has, the other replaces it.
/// Collapsing them would leave the client splicing a window onto rows it has no
/// way to know are no longer adjacent -- a seam that looks like ordinary output.
#[derive(Debug, Clone, PartialEq)]
pub enum CatchUp {
/// The events after the cursor, continuing what the subscriber holds.
Continue(Vec<SeqEvent>),
/// The subscriber was further behind than [`CATCH_UP_LIMIT`]: the newest
/// window, replacing whatever it holds. Earlier history is still there to be
/// paged backwards through.
Restart(Vec<SeqEvent>),
}
/// Everything after `after`, or the newest `limit` when that is more.
///
/// The window is chosen before anything is parsed, which matters most in the
/// case that looks least interesting: a subscriber with no cursor asks for the
/// whole conversation and is handed the last [`CATCH_UP_LIMIT`] events of it,
/// so parsing the discarded prefix is the whole file's work for a screenful.
pub fn catch_up(path: &Path, after: u64, limit: usize) -> Result<CatchUp> {
let Some(indexed) = Indexed::read(path)? else {
return Ok(CatchUp::Continue(Vec::new()));
@@ -210,9 +145,6 @@ pub fn catch_up(path: &Path, after: u64, limit: usize) -> Result<CatchUp> {
Ok(CatchUp::Continue(indexed.parse(start..end)?))
}
/// Replays every event with `seq > after`, oldest first. A missing file is
/// an empty transcript, not an error -- the session just hasn't produced an
/// event yet.
pub fn read_after(path: &Path, after: u64) -> Result<Vec<SeqEvent>> {
let Some(indexed) = Indexed::read(path)? else {
return Ok(Vec::new());
@@ -221,32 +153,13 @@ pub fn read_after(path: &Path, after: u64) -> Result<Vec<SeqEvent>> {
indexed.parse(start..indexed.lines.len())
}
/// The transcript's lines located but not read, so a reader can find the range
/// it wants and parse only that.
///
/// Both readers above want a *range* of the file, and both used to reach it by
/// parsing every line and discarding the ones outside it -- the cost that grows
/// with the conversation rather than with the answer. Measured on a 21 MB,
/// 24,000-event transcript, one page took **500 ms of server time to return
/// 600 KB**, and the same 500 ms whichever page was asked for. A phone paging
/// back pays it per page, and every stream reconnect pays it again to discover
/// there is nothing new.
///
/// Sequence numbers only ever increase, so the boundary of a range is a
/// bisection: this parses one line per halving, and the caller parses only what
/// it returns. The file is still read whole, which is a deliberate stop --
/// going further means a chunked backwards reader, and locating a line is not
/// what the half-second was going to.
struct Indexed<'a> {
path: &'a Path,
text: String,
/// Byte range of each non-blank line, in the order they were written.
lines: Vec<Range<usize>>,
}
impl<'a> Indexed<'a> {
/// `None` for a file that isn't there, which is a session that has not
/// produced an event yet rather than a failure.
fn read(path: &'a Path) -> Result<Option<Self>> {
let text = match std::fs::read_to_string(path) {
Ok(text) => text,
@@ -270,9 +183,6 @@ impl<'a> Indexed<'a> {
Ok(Some(Self { path, text, lines }))
}
/// The index of the first line numbered `seq` or higher, or the end when
/// every line is older than that.
///
/// A bisection, which is only correct because the file is in sequence order.
/// A line that cannot be read is reported here rather than silently treated
/// as out of range, because the answer would be a window off by however much
@@ -290,7 +200,6 @@ impl<'a> Indexed<'a> {
Ok(low)
}
/// One line's sequence number, without building the event on it.
fn seq_at(&self, index: usize) -> Result<u64> {
#[derive(Deserialize)]
struct JustSeq {
@@ -317,24 +226,8 @@ impl<'a> Indexed<'a> {
.with_context(|| format!("bad transcript line in {}", self.path.display()))
}
/// The newest `limit` *rows* ending at line `end`, with each run of
/// consecutive [`Event::AssistantText`] deltas concatenated into one.
///
/// A reply is stored a token at a time, so a window counted in events is a
/// fraction of a row for a reply and a whole row for a tool call, and the
/// phone can neither predict how much a page will show nor fill a screen
/// without folding a page of near-duplicate events. Counted in rows, a page
/// is a page.
///
/// A run takes the seq and time of its *oldest* delta, matching the phone's
/// own rule -- so anchors and the `before` cursor land where they always
/// did. A run cut by the `limit` is emitted as the partial it is, and the
/// phone's `healSplitMessage` welds it to the next page. `start` is the same
/// kind of cut from the other end.
fn parse_coalesced(&self, start: usize, end: usize, limit: usize) -> Result<Vec<SeqEvent>> {
// Newest first while walking back, reversed to transcript order at the end.
let mut out: Vec<SeqEvent> = Vec::new();
// The run currently being gathered: its oldest seq/ts so far, and its deltas newest-first.
let mut run: Option<(u64, f64, Vec<String>)> = None;
let flush = |run: &mut Option<(u64, f64, Vec<String>)>, out: &mut Vec<SeqEvent>| {
if let Some((seq, ts, mut deltas)) = run.take() {
@@ -350,9 +243,6 @@ impl<'a> Indexed<'a> {
};
let mut index = end;
while index > start {
// A row is counted when it lands in `out`; an open run is the row
// being gathered, so stopping while one is open would drop the
// deltas already read. Break only between rows.
if out.len() >= limit && run.is_none() {
break;
}
@@ -368,7 +258,6 @@ impl<'a> Indexed<'a> {
None => run = Some((entry.seq, entry.ts, vec![delta])),
}
} else {
// The run above this event (newer) is complete: it is a row, and so is this event.
flush(&mut run, &mut out);
out.push(entry);
}
@@ -406,7 +295,6 @@ mod tests {
assert_eq!(replay[0].event, text("b"));
assert_eq!(replay[1].seq, 3);
// A cursor at or past the end replays nothing.
assert!(read_after(&path, 3).expect("read").is_empty());
}
@@ -435,15 +323,12 @@ mod tests {
.expect("append");
}
// Within the limit the subscriber keeps what it has.
let CatchUp::Continue(events) = catch_up(&path, 7, 5).expect("catch up") else {
panic!("a backlog of 3 should continue");
};
assert_eq!(events.len(), 3);
assert_eq!(events[0].seq, 8);
// Past it, the newest window replaces what it has -- and it is the
// newest, not the oldest, that survives the trim.
let CatchUp::Restart(events) = catch_up(&path, 0, 5).expect("catch up") else {
panic!("a backlog of 10 should restart");
};
@@ -451,9 +336,6 @@ mod tests {
assert_eq!(events[0].seq, 6);
assert_eq!(events[4].seq, 10);
// Exactly at the limit is still a continuation: the boundary belongs to
// the cheaper answer, so a client is not reset for being one event
// behind the threshold.
assert!(matches!(
catch_up(&path, 5, 5).expect("catch up"),
CatchUp::Continue(_)
@@ -465,8 +347,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
// Nothing recorded yet: no prior state to report, which is not the same
// as reporting idle.
assert_eq!(Transcript::open(&path).expect("open").last_status(), None);
let mut transcript = Transcript::open(&path).expect("open");
@@ -486,13 +366,11 @@ mod tests {
2.0,
)
.expect("append");
// Events after the last status must not hide it.
transcript.append(text("trailing"), 3.0).expect("append");
drop(transcript);
let reopened = Transcript::open(&path).expect("reopen");
assert_eq!(reopened.last_status(), Some(SessionStatus::Exited));
// And the same pass still continues the numbering.
assert_eq!(reopened.next_seq, 4);
}
@@ -507,22 +385,18 @@ mod tests {
.expect("append");
}
// No cursor is the newest page, which is what opening a session asks for.
let newest = read_window(&path, None, None, 3, false).expect("window");
assert_eq!(
newest.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[8, 9, 10]
);
// Then backwards from the oldest of those, exclusive: the page a phone
// scrolling up asks for must not repeat the row it is scrolling from.
let older = read_window(&path, Some(8), None, 3, false).expect("window");
assert_eq!(
older.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[5, 6, 7]
);
// Asking for more than there is gives what there is, rather than failing.
assert_eq!(
read_window(&path, None, None, 100, false)
.expect("window")
@@ -530,8 +404,6 @@ mod tests {
10
);
// Nothing before the first event, which is how the phone learns to stop
// paging. An empty answer here is the end of the history, not a fault.
assert!(
read_window(&path, Some(1), None, 3, false)
.expect("window")
@@ -555,24 +427,18 @@ mod tests {
.expect("append");
}
// The floor is exclusive, like the SSE route's `after`, and it -- not the
// limit -- is what the page stops at. This is the gap between a phone's
// cached run and the window on its screen, fetched exactly.
let page = read_window(&path, Some(9), Some(5), 100, false).expect("window");
assert_eq!(
page.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[6, 7, 8]
);
// A limit smaller than the gap still bites; the floor is a bound, not a
// replacement for one.
let page = read_window(&path, Some(9), Some(2), 3, false).expect("window");
assert_eq!(
page.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
[6, 7, 8]
);
// A floor at or above the window is an empty page, not a walk past it.
assert!(
read_window(&path, Some(4), Some(9), 10, false)
.expect("window")
@@ -599,9 +465,6 @@ mod tests {
)
.expect("append"); // seq 5
// Cut inside the run: what comes back is the deltas above the floor, seq'd
// at the first of them -- the partial the phone's `healSplitMessage` welds
// onto the rest, the same as a run cut by the limit.
let rows = read_window(&path, Some(6), Some(2), 10, true).expect("window");
assert_eq!(rows.len(), 2);
assert!(matches!(
@@ -617,7 +480,6 @@ mod tests {
}
));
// And with no floor the whole run is one row, as before.
let rows = read_window(&path, Some(6), None, 10, true).expect("window");
assert_eq!(rows.len(), 2);
assert!(matches!(
@@ -631,8 +493,6 @@ mod tests {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
let mut transcript = Transcript::open(&path).expect("open");
// Two replies of three deltas each, split by a tool call: the shape a turn writes, and
// the one an event-counted page cannot see a row of.
for d in ["a", "b", "c"] {
transcript.append(text(d), 0.0).expect("append"); // seq 1..3
}
@@ -650,12 +510,8 @@ mod tests {
transcript.append(text(d), 0.0).expect("append"); // seq 5..7
}
// Three rows asked for, three rows returned -- each delta run one event -- where a raw
// window of three would have shown one and a half tokens of the newer reply.
let rows = read_window(&path, Some(8), None, 3, true).expect("window");
assert_eq!(rows.len(), 3);
// A run keeps its oldest delta's seq, so the phone anchors and pages from where it always
// did.
assert!(matches!(
&rows[0],
SeqEvent { seq: 1, event: Event::AssistantText { delta }, .. } if delta == "abc"
@@ -673,11 +529,9 @@ mod tests {
SeqEvent { seq: 5, event: Event::AssistantText { delta }, .. } if delta == "def"
));
// The next page pages from the oldest row's seq and returns the rest, no repeat, no gap.
let older = read_window(&path, Some(1), None, 3, true).expect("window");
assert!(older.is_empty());
// The newest window never coalesces even when asked: the live cursor depends on real seqs.
let newest = read_window(&path, None, None, 2, true).expect("window");
assert_eq!(newest.iter().map(|e| e.seq).collect::<Vec<_>>(), [6, 7]);
}
@@ -686,17 +540,6 @@ mod tests {
fn a_line_read_back_is_the_line_that_was_written() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("transcript.jsonl");
// A timestamp with enough digits to be lost: the clock produces these all day, and this
// one is real (2026-09-04). serde_json's default float parser is not correctly rounded,
// so it read this back as ...0755 and every reader got a line one bit different from the
// one in the file -- while the SSE stream, which serializes the same struct, had already
// sent the original. Two answers to "what is line 1", indistinguishable by eye.
//
// Nothing on screen showed it: a `ts` is drawn as a relative time. What found it was the
// phone's transcript cache, which keeps the line it was sent and checks it against the
// server's own answer before resuming a stream from it -- so the mismatch turned into a
// cache thrown away and a transcript downloaded again, silently and only sometimes. The
// `float_roundtrip` feature in Cargo.toml is the fix; this is what keeps it.
let mut transcript = Transcript::open(&path).expect("open");
transcript
.append(text("hello"), 1788546972.6030757)