ai-app/CLIENT_CORE.md

# client-core

`client-core/` is the app's pure logic held once instead of twice, per
RUST.md's recommendation item 1. It is a plain Rust library crate with no UI
framework dependency of any kind, so it can outlive whichever one the app
ends up drawing with (Masonry, iris, or something else -- see RUST.md).
`event-model/` is its sibling: the wire shape both this crate and `server/`
share, extracted from `server/src/session/driver.rs` and
`session/transcript.rs` on 2026-09-04.

Neither crate is wired into anything yet. `server/` re-exports `event-model`
so its own behaviour is unchanged (`./run-tests.sh` covers it); `client-core`
has no caller -- it exists for whichever experiment in RUST.md picks it up
next (a Masonry or iris transcript screen, most likely).

## What's here, and what Kotlin file it replaces

| `client-core/src/…`                     | Kotlin original                          | Status |
|------------------------------------------|-------------------------------------------|--------|
| `event-model/src/lib.rs` (shared crate)   | `Events.kt` (the enum mirror)             | Done   |
| `ansi.rs`                                 | `Ansi.kt`                                 | Done, ported test-for-test |
| `highlight/mod.rs`, `languages.rs`        | `Highlighter.kt`, `Languages.kt`          | Done, ported test-for-test |
| `highlight/markdown.rs`                   | `MarkdownSyntax.kt`                       | Done, ported test-for-test |
| `transcript_cache.rs`                     | `TranscriptCache.kt`                      | Done, ported test-for-test |
| `sse.rs`                                  | `Sse.kt` (the framing half)               | Done, new tests (Kotlin had none of its own beyond integration) |
| `api.rs`                                  | `Api.kt`                                  | Partial -- see below |
| `event_stream.rs`                         | `EventStream.kt`                          | Done |
| `transcript_fold.rs`                      | `TranscriptItems.kt`, `ToolRows.kt`       | Partial -- see below |
| *(not started)*                           | `TranscriptSource.kt`                     | Not started |
| *(not ported, and may never be)*          | `TranscriptUnits.kt`                      | Out of scope -- see below |

Every file above whose Kotlin counterpart had a JVM unit test (`AnsiTest`,
`HighlighterTest`, `TranscriptCacheTest`) has had every one of those test
cases ported alongside it, plus new tests for the pieces that had none
(`sse.rs`, `api.rs`, `event_stream.rs`, `transcript_fold.rs`). Test count by
crate as of this writing: **85 in `client-core`**, 0 in `event-model` (its
types carry no logic of their own to test -- `server/`'s own tests exercise
them via `session::transcript`'s round-trip coverage).

## Correspondence notes worth knowing before touching either side

- **`ansi.rs`'s `StyledText`/`Style`/`Rgb`** stand in for Compose's
  `AnnotatedString`/`SpanStyle`/`Color`, since this crate has no Compose.
  `StyledText` is plain text plus a `Vec<(Range<usize>, Style)>` of
  non-overlapping spans. Whatever UI framework ends up consuming this
  crate maps `Style` onto its own text-styling type; nothing here should
  change to accommodate a particular one.
- **`highlight`'s `Span`/`Kind`** use **char indices, not byte offsets**
  (`Vec<char>` internally), mirroring the Kotlin original's `Char`-indexed
  strings. `highlight::span_text` turns a `Span` back into text for a
  caller working the same way; a caller that wants byte offsets into a
  `&str` has to convert.
- **`transcript_cache.rs`'s `SessionCache::guard`** found a real
  translation bug while it was being written: an early draft let a
  *damaged* chunk (one file unreadable, discard just this session) and a
  genuine I/O failure (disk gone, disable the whole cache) both surface as
  the same `Err` from one closure, which would have disabled every
  session's cache over a single corrupt chunk. Fixed by checking a
  thread-local "was this damage" flag before deciding which failure mode
  it was -- see the comment on `guard` and the commit message for
  `transcript_cache.rs`.

## What `api.rs` covers, and what it does not yet

`ApiClient` wraps a `Transport` trait (network I/O kept out from behind, so
`ApiClient` and `event_stream::follow_session_events` are tested with a
fake transport and no server). `UreqTransport` is the only real
implementation, backed by `ureq` -- see its Cargo.toml comment for why
(blocking, already a project dependency, no extra TLS crate needed since
`ureq::tls::Certificate::from_pem` reads the pinned CA directly).

Covered: session list/read, message send, unqueue, answer, interrupt,
stop, start, rename, cwd, model, permission-mode, notify, command,
compact, delete, and one transcript page.

**Not covered, and each is real work rather than a stub to fill in:**
setups (`/setups*`, machine and provider discovery), the file explorer
(`/setups/{id}/dir|file`), usage (`/usage`), models
(`/models*`, HuggingFace browsing and downloads), attachments
(`/sessions/{id}/attachments`), importing (`/setups/{id}/importable*`),
and the `/notifications` stream. `server/src/routes.rs`'s module doc is
the full table to work from when one of these is next.

## What `transcript_fold.rs` covers, and what it does not yet

`fold_event` covers every `Event` variant server/ can produce today,
including tool-call/question/image attachment and peer-message placement.
`group_tool_runs` groups adjacent calls into `TranscriptRow::Tools`.

**Not ported:** `TranscriptItems.kt`'s `joinPages` (and its
`healSplitMessage`/`adoptRun` helpers) -- the page-boundary healing that
merges a tool call split across two fetched pages and re-merges a run a
boundary cut through. This matters the moment paging backward through
history is exercised; it is deliberately left rather than rushed, since
it is exactly the kind of boundary logic this project's own "things that
have bitten" section warns reads fine and is wrong at the edges.

**Known gap, and a decision for whoever closes it:** `event_model::Event`
has no `Unknown`/catch-all variant, unlike `Events.kt`'s hand-kept mirror.
A server newer than this build that adds an event type will fail to parse
that line rather than degrading to a placeholder row. Closing this means
deciding how `event_model` itself represents "a shape I don't recognise"
-- a shared-model decision affecting `server/` too, not a `client-core`-only
fix, so it is recorded here rather than silently worked around.

## What is not started at all

- **`TranscriptSource.kt`** -- the layer that decides whether a page comes
  from the transcript cache or the server, and stitches the two. Needs
  `transcript_cache.rs` and `api.rs`'s transcript-page method, both of
  which exist now, so this is unblocked whenever picked up.
- **The markdown *block* model beyond syntax spans** -- `highlight/markdown.rs`
  colours a `.md` file or fence for the highlighter, but does not build the
  block tree (headings, lists, tables, fences as distinct nodes) that a
  renderer walks to lay out prose versus code versus a table.
  `CodeFence.kt`'s use of `org.intellij.markdown` for that full CommonMark
  AST is Compose rendering plumbing, not something to port as-is; a Rust
  UI layer will want its own block parser or a crate for it, decided
  alongside the framework choice in RUST.md.
- **`TranscriptUnits.kt`** (see above) -- deliberately out of scope, since
  it flattens a row into bounded units for a *specific* lazy-list
  framework's composition cost, which is a fact about that framework
  rather than about the transcript.

## Verifying

`./run-tests.sh` from the repo root now runs `event-model`, `client-core`
and `server` in that order (each `cargo test`, forwarding arguments the
same way it always has). From `client-core/` directly: `cargo test`,
`cargo clippy --all-targets`, `cargo fmt` -- all clean as of this writing.