# `improvise-protocol` — the wire vocabulary and the portable session slice

The arguments that used to live in this crate's comments (improvise-9c8c).
Written for a reader who has the code open. Nothing here restates what the
code plainly says; everything here is something somebody got wrong first.

The crate crosses a process boundary, so it depends on `improvise-core` and
`serde` and nothing else — no terminal backend, no command layer, no IO.
`improvise-command` depends on *this*, never the reverse, and that direction
is what lets a client hold the view half without pulling in the host.
`boundary_tests::the_wire_types_need_nothing_but_core_and_serde` is the part
the compiler can hold; the CI `wasm` job is the other half, since a crate
that pulled in crossterm would stop building for wasm32.

Three things live here and it is worth being precise about which travels:

- **`ViewState`** (`lib.rs`) is a *projection of the command stream*, not a
  wire message. The server keeps a mirror of each client's view state by
  applying the same commands the client applies, through the shared
  `reduce_view`. It is serialized at exactly one point — the bootstrap
  `Snapshot` (improvise-q08). Steady-state traffic is commands only.
- **`Command`** (`reduce.rs`) is the wire format, in both directions: user
  intent client→server, `Projection`s server→client.
- **`ClientFrame`/`ServerFrame`** (`frame.rs`) is the *framing* rather than
  the vocabulary: which of the above a given JSON blob is.

---

## 1. `lib.rs` — the portable slice

### What may live on `ViewState`

Two properties gate membership, and both are load-bearing (improvise-h0b):

- **portable** — plain data from the allowlisted crates, no shared-ownership
  containers. The `ViewState: Send` static assertion is the compile-time
  proxy (`Rc` is not `Send`); the `Deserialize` derive rejects it too, serde's
  `rc` feature being off. `Send` does **not** catch the origin-crate or
  snapshot-safety halves — check those by hand.
- **snapshot-safe** — a fresh client inheriting the value is *correct*.
  Staged uncommitted writes and half-open dialogs are not.

State failing either test lives on `App` instead, under the *session-local
residue* tag: `wizard` (an `improvise-io` type, and a half-open dialog is not
something to inherit) and `drill_state` (holds an `Rc`, and `pending_edits`
are uncommitted writes belonging to whoever staged them).

The constraint this puts on new fields: **no borrowed-`'static` fields
anywhere `ViewState` can reach** — `Deserialize` cannot produce one, and the
error surfaces on every *enclosing variant* rather than at the offending
field. That is why `MinibufferConfig::buffer_key` is a `String` and not a
`&'static str` (improvise-a2x).

### `ViewCursor` and the `cursors` map

Per-client (improvise-8uz). It used to live on `View`, inside the shared
workbook, which meant one client scrolling moved everyone's viewport. `View`
no longer carries it at all — nothing persisted it, so there was no
saved-position behaviour to preserve. The map is keyed by view name so that
switching views restores where you were in each one; an absent key means the
origin.

### `ViewState::active_view` is the second copy, deliberately

`Workbook::active_view` is the document's; `ViewState::active_view` is the
client's, and it is what keys `cursors`. The second copy exists because
`reduce_view` runs on a client that holds no `Workbook` (improvise-cqi). The
host keeps the two in step; whether they are *allowed* to diverge — two
clients on different views — is improvise-g0f. See repo-map gotchas 29/36.

### `AppMode::from_name` — not every variant is nameable

The list is exactly what `improvise-command`'s registry accepted before the
move, carried across unchanged, because changing it here changes what
`enter-mode` accepts in a script. It lives beside `AppMode` rather than in
the registry because the *names* are part of the keymap vocabulary and the
keymap is shared: a browser resolving `enter-mode` must decode the same
spellings, and two tables would be the mirror that move existed to delete.

Three variants are absent, for two reasons. `ItemAdd` resolves its target
category from the runtime mode and never from a script line (gotcha 20), so
naming it would produce a mode with nothing to add to. `Quit` and
`ImportWizard` are entered by their own commands — `quit` and
`start-import-wizard` — which do work beyond changing the mode, so
`enter-mode` would be a way to reach half of each.

### `Panel`

`Panel::ALL`/`name()`/`key()` drive the toggle keys for Normal *and* all
three panel keymaps, so a fourth panel reaches every keymap from one `ALL`
entry. `name()` must spell what `parse_panel` accepts. `Panel::mode()` is the
inverse of `AppMode::panel()` for the three top-level panel modes only — the
sub-modes (`FormulaEdit`, `CategoryAdd`, `ItemAdd`) map back to their panel
but not forwards, which is what keeps a panel's styling active while the user
types into its minibuffer.

`AppMode::hint_text()` is checked against the keymaps by
`every_hint_key_resolves_in_its_mode` in `improvise-command`; `Quit` alone
shows nothing, because it is never rendered.

---

## 2. `reduce.rs` — the wire vocabulary

### Derived, not invented

`Command` is not a fresh invention
(`doctrine(derive_the_enum_from_the_effects)`):

- The **view half** is every `EffectKind::ViewOnly` effect in
  `improvise-command` whose target is the portable slice
  (`decision(improvise-cqi, command_set_derived_not_invented)`). Effects
  touching host-local state (the import wizard, staged drill edits, the
  storage backend, the layout cache) are deliberately absent.
- The **model half** is `ModelCommand`: every `EffectKind::Model(..)` effect,
  one variant apiece, carrying that effect's own fields (improvise-kmgs).

The count is 29 model effects, minus three: `SwitchView`, which `Command`
already names and routes, and `ApplyAndClearDrill`/`AcceptWizardModel`, which
are **not addressable** (improvise-3x3u). That leaves **26**. A variant with
no data mirrors a nullary effect whose operand is document state the
authoritative `App` already holds.

Two derivation traps worth keeping:

- The obvious `awk` extraction reports **30** — it picks up `HelpPageSet`,
  which is `ViewOnly`, because that is the last `pub struct` before
  `#[cfg(test)]` and the test module mentions `ModelChange::`. Brace-match
  the `impl Effect` blocks instead (`doctrine(derive_then_verify)`).
- improvise-kmgs derived the set **one effect at a time**, which was correct
  per element and wrong for a set: it put `SetCell` on the wire without its
  `MarkDirty` companion, so "save if dirty" never fired (improvise-gv9r).
  `MarkDirty` is gone; `App::apply_effects` now raises the flag off
  `EffectKind::Model(_)` directly.

### Why two model effects are key-path only

A command on this wire is routed by `Sessions::apply` with **no
`SessionId`**, which is correct precisely when the change is addressed to no
one session (gotcha 36). `ApplyAndClearDrill` and `AcceptWizardModel` fail
that test: their operands — `drill_state.pending_edits` and the built wizard
workbook — are session-local residue, private to whoever staged them
(improvise-tom1). Unaddressed, client B's `ApplyAndClearDrill` commits client
A's uncommitted typing, and B's `AcceptWizardModel` replaces the document out
of a dialogue B never opened. Both were demonstrated against `Sessions::apply`
before removal.

*Portability of the command* was the criterion when they were kept;
**addressability** is the criterion that matters. Not permanent: multi-client
drill wants the addressed form (the variant carries a `SessionId`, the staging
map moves onto the session), which is where ADR 001 layer 2 goes anyway.

### `Command::SwitchView` has a foot in both halves

The `SwitchView` *effect* wears `EffectKind::Model(LayoutGeometry)`, so the
model-half derivation lands on it too — and `ModelCommand` deliberately does
**not** name it a second time (improvise-kmgs). `ModelCommand::ViewBack` and
`ViewForward` also move the active view and so carry the same document half.

### `Command::ResetCursor` is an invalidation, never a position

Derived from `App::reset_cursor`, the write `TransposeAxes` and `CycleAxis`
make after changing the grid's shape (gotcha 24). It is a variant rather than
a `SetSelected` plus two offsets for a reason that is not brevity: what the
server says is **"your cursor is no longer valid"**, not "be here". Where a
client then puts its cursor is its own business — the model is shared, the UI
is not — so broadcasting one client's position to everyone would be the wrong
message even though origin happens to be where each of them lands today
(improvise-gvnb).

### `Command::Model` is a struct variant

So the basis cannot be forgotten. ADR 001's check is worth nothing if a batch
may arrive without one, and the only enforceable version of "you must also
state X" is not being able to build the message without X. There is no
`Basis::default()` for the same reason — see §5.

Note what the struct variant does *not* buy: it closed omission **from the
message** and did nothing to close ignoring **on arrival**, which is the half
a struct variant is usually reached for. That hole needed a type —
`Checked`/`CheckedBatch` in `improvise-command` (improvise-ondj).

### `ModelCommand::SetCell` takes a `RecordCell` and nothing else

A `CellKey` here would require the client to know the coordinate space —
every row and column category plus the page and filter selections (gotcha
27), and in records mode the `_Dim` column-index convention (gotcha 1) —
which is precisely the knowledge the server exists to own. The surrogate is a
token to echo back; and because it is a *record* identity, a client holding
one for an aggregate cell cannot build this variant at all (ADR 002).

`LoadModel` and `ImportJsonHeadless` name paths in the **host's** `Storage`,
never the client's filesystem (gotcha 2).

The variants are grouped by the `ModelChange` level their effect declares,
because that level is what `Dirty::of` turns into projections (gotcha 35).
Adding a variant here means classifying its effect there.

### `reduce_view`

The same function runs on both ends — the client folds it to draw, the server
folds it over its mirror — so the two cannot drift (improvise-cqq,
improvise-m91). Total and deterministic: no IO, no clock, no failure.

`Command::Project` and `Command::Model` are both no-ops in it, for different
reasons. A projection is routed to one widget's `WidgetCache` instead. A
model command is the *document's* business: what a client must fold arrives
as the projections it dirtied, plus — when the active view moved — the
`SwitchView` the host broadcasts.

A `ModelCommand` does not mutate anything by itself: `improvise-command`'s
`model_effects` maps it back to the effect it came from and runs it through
the same `App::apply_effects` the key path uses. Effects stay the only
mutation site, and the `Dirty` is the effect's own `EffectKind` — never a
second classification beside gotcha 35's table.

---

## 3. `render.rs` — the fold

### There is no aggregate render cache

Each widget owns its own cache type and folds its own stream of projections
(improvise-rkeq): the grid does not learn that a formula was deleted, and the
formula panel does not learn that a cell changed. A `Projection` is one such
update, addressed to exactly one widget, and `WidgetCache::apply` is the fold.

The overlap between `TileBarCache` and `CategoryTreeCache` — both carry
`(category, axis)` — is **deliberate**, so neither is woken by the other's
changes. Do not "fix" it by sharing a variant.

`WidgetCache::apply` is total and deterministic, like `reduce_view`: an
update naming something the cache does not have is **dropped, never a panic**.
Projections race on the wire, and a client that crashes on a stale index is a
client that crashes.

`Projection::Basis` is not a widget — nothing draws it — but it is folded on
exactly the same terms; see §5.

### `DocumentCache` — a widget, not a `ViewState` field (improvise-z754)

`draw_title` read `workbook.model.name`, `model_state.dirty` and
`model_state.file_path`. None was projected, so a browser could not draw a
title bar at all.

**A projection rather than a `ViewState` field**, and the argument is gotcha
30's membership test read backwards. `ViewState` is the *portable session
slice*: per-client UI a client folds its own commands into. These three are
facts about the **document**, shared by every client and writable only by the
server — on `ViewState` they would be document state wearing a session slice's
clothes, and `reduce_view` would need commands nothing composes. The
per-widget cache is exactly the shape for "a local copy of what a widget
draws, replaced by a `Projection`".

**It is the one widget no `EffectKind` can gate.** `dirty` is raised by any
`EffectKind::Model(_)` in `apply_effects` and cleared by `effect::Save`, which
is `ViewOnly` (gotcha 3) and correctly so. `SaveAs` moves `file_path` and is
also `ViewOnly`. So `Dirty::of` reports `NOTHING` for exactly the effects that
change this widget most visibly, and gating it on `Dirty` would leave every
client showing a `[+]` for a document that has been saved — the forever-wrong
half of gotcha 35. `ClientSession::document_update` therefore **observes**: it
builds the desired cache and diffs it against the mirror, the same answer
`record_versions` got for the same reason (gotcha 40), and the same reason
`cursor_epoch` beats matching on `CycleAxis`. The diff, not a flag, is what
keeps an ungated widget from projecting on every batch.

**A save is projected, not silent.** `Host::save` ends with `project_all()`
and the worker re-projects after its own `persist()`, because both clear
`model_state.dirty` *outside* any batch `Dirty` describes. gotcha 45's
"answered silently on success — nothing moved, so no widget is dirty" was true
until this cache existed and is now exactly wrong: the title bar moved. A test
that reaches for `Sessions::project_all` by hand proves nothing here, because
that is the call the production paths omitted.

**`stored_as` is a name, never a path.** The TUI already drew only
`file_name()`, and a socket server projecting `file_path` would hand a remote
client the host's directory layout — useless to it and a leak. What a client
can act on is *whether the document has a home at all*, which is the fact
`ClientFrame::Save` fails on (`NoDocumentPath`, gotcha 45), so `None` carries
it. A browser's answer is its OPFS entry name; neither end has to know which.

### `CellId`: the kind of identity is the permission

`SetCell`/`ClearCell` take a `RecordCell` and nothing else, `Drill` takes an
`AggregateHash` and nothing else. A client cannot compose a write against an
aggregate **or** a drill against a stored cell — not because either is
checked, but because neither carries an id of the other's type
(design-principles §3). It projects a fork the model already makes:
`EditOrDrill` branches on exactly this in the TUI today.

An earlier draft made this `Option<CellId>`, absence meaning aggregate. The
enum is better: an aggregate is not the *absence* of an identity, it is a
different *kind* of identity — and modelling it as `None` left `Drill` with
nothing to address.

A `RecordCell` is `(record hash, measure)` because the surrogate names the
**record**, not the cell (ADR 002). That is what lets one identity serve both
addressing and staleness: `record_versions` is keyed by the same hash, so a
client's own token is the lookup key for its own version, with no `CellKey`
rebuilt on the hot path. `measure` is absent for a record carrying no
`_Measure` coordinate at all — the shape `add-record-row` seeds.

### `CellId::Derived` — a formula owns the cell (improvise-ir7l)

A formula target is a real stored coordinate, so the record branch claimed it
and every client offered an editor over it. The write *landed* and was then
shadowed forever, because `evaluate_aggregated` reads `formula_cache` before
raw data — not a revert, a permanent silent shadow.

The fix keeps ADR 002's discipline rather than adding a second answer beside
it: a formula-owned cell projects a **different kind of identity**, so the
write is unconstructible instead of flagged. `Derived` carries the formula's
target and **no surrogate**, so there is nothing a client could spend on a
`SetCell`; that is the same reason `Aggregate` carries an `AggregateHash` and
not a `RecordHash`.

**In records mode the question is asked of the record's real coordinate.** The
synthetic `(_Index, _Dim)` key names no measure, so `formula_for` can never
match it; `GridLayout::record_cell_key` is the one mapping from a records
position to a model cell, and both `cell_id` and `CmdContext::owning_formula`
go through it. This is not defensive: a measure can be **both** an explicit
`_Measure` item and a formula target, and the records `+` column
(improvise-poia) is a one-keystroke way to build one.

Two orderings matter in `project::cell_id`. Derived is asked **before** the
record branch, since the coordinate is stored and the record branch would
otherwise win. It is asked **after** the aggregate branch, because a formula
cell that also aggregates is still drillable (gotcha 10) — `Aggregate` and
`Derived` are not alternatives for the same cell, and reversing the two turns
a drillable cell into a dead one.

The predicate itself is `Model::formula_for(&CellKey)` in `improvise-core`,
the one home of "is this cell derived". It already existed three times inside
`model/types.rs` as an open-coded loop; the TUI's `EditOrDrill` and the
producer now call the same function rather than each spelling the rule. The
TUI had to change in the same breath: it re-derives from the `Model` it holds,
which is legitimate (it is the authority), but it must give the *same* answer
or the two front ends diverge — design-principles §5.

### `CellId::Create` — the column writes no cell (improvise-poia)

The two records-mode creating columns — `+` and `+cat` (gotcha 1) — projected
`None`, which means "no projected cell". So a client could not tell a column
that creates something from a padded slot, and gotcha 42's conflation had a
third instance.

**The ticket offered two designs and both assumed a cell write.** They do not
happen: `commit.rs::add_measure` emits exactly one effect,
`AddItem { category: "_Measure", item: name }`, and `add_category` emits
`AddCategory(name)` and deliberately writes no coordinate on the current row
(improvise-2zq). The record under the cursor is not part of the operation, and
neither is any value — **what the user types is a name**. So there is no
"distinct command carrying the record surrogate plus the new measure name" to
invent, and no two-command flow to sequence: one existing `ModelCommand` does
it, and the address it needs is the name.

What was missing was therefore never an address but a **recognition**. `Create`
carries the kind and nothing else, because the kind plus the typed name is the
whole operand. It is not a `SetCell` target, so `render.rs::editable` stays
`Record`-only and `record_at_cursor` still answers `None` — both by matching,
which the compiler now forces.

**No client composes it yet**, and that is one gap rather than this one:
`keys.rs::commit` returns early for every records-mode commit, because a
category column renames every measure cell in the row and that fork needs
`record_col`. The creating columns do not need it, so the early return is
broader than its reason — improvise-gcvb, which also records the two things
that make it more than a one-liner: an inserted `+cat` column means the TUI
does **not** advance, and `AddCategory` can abort.

### `CellDisplay::id` — `None` is not "aggregate"

That is `Some(CellId::Aggregate(..))`, and the distinction is the whole point
of the enum. `None` means the slot holds **no projected cell**: a `GridCache`
position padded by `fit_to_labels`, blanked by a reframing, or a
records-mode column that is not a cell to write into at all (a category column
renames a coordinate across the whole row, gotcha 1, which is a different
intent from `SetCell`). Conflating the two either hides a cell or offers a
write the type system exists to make unconstructible.

### `CellDisplay::edit_text` — the difference corrupts data

What an editor opened on this cell should start with: the value as the user
last **typed** it, not as it is **drawn**. `text` has been through
`format_f64`, so a stored `1200` is drawn `1,200` under a comma-grouping
format; seeding an editor with that and committing it parses as
`CellValue::Text("1,200")`, and the number is gone. Display rounding is
view-only and must never be fed back into the model (design-principles §4) —
and an editor's seed is exactly a feedback path.

It is the projection of `App::display_value_at_cursor`, which is what
`EditOrDrill` seeds the TUI's buffer from, so both front ends start from one
string rather than each deriving one. `None` where there is nothing to edit:
the same set of positions `id` is `None` for, plus cells whose value is
absent. An error cell carries none, because its text is a diagnostic and not
a value.

A browser found this: `tests/lockstep.rs` drove `i` through the host and the
client over the same grid, and they disagreed by a comma.

`numeric` and `error` are decided by the server for the same reason: it is
the side that knows which it was, and re-deriving client-side is how the two
ends drift apart. `CellDisplay` is deliberately not a `CellValue` — by the
time a cell reaches a client the number formatting has already happened.

### `AxisFrame` — the grid's frame, and why it is *one* type

`AxisFrame` (improvise-anr9/s1xw) replaced a `Vec<String>` of labels that
`GridLayout::row_label` built by **slash-joining a multi-level tuple** — the
exact rendering `two_row_categories_produce_cross_product_labels` asserts must
not appear. The protocol carried a form of the labels the TUI itself
considered wrong, so the browser drew `Food/Alice` where the TUI drew two
header columns, with no groups and no collapse indicators (gotcha 44).

It is one type rather than a `labels` plus a `levels` beside it, and that is
the whole point: **two answers to "what are the labels" is the disease** this
projection architecture exists to cure (improvise-edp). A renderer asks this
type and there is nothing else to ask. Note what this cure cost that
`flatten_cat_tree` did not: a `Vec<String>` had to change **type**, and the
shared derivation could not be added beside the old one.

`cats` is the categories outermost-first; `entries` interleaves
`Group(FrameGroup)` headers with `Item(Vec<String>)` label tuples exactly as
`GridLayout::row_items` interleaves them. On the row axis the TUI paints a
`Group` as its own row; on the column axis it paints the runs as spans above
the headers. **That difference is painting, and it is the only thing that
differs.**

`cats` may be empty — an axis carrying no category is a real layout (one
nameless row or column), not a gap, hence `levels()` returning **at least
one**. `AxisFrame::flat` leaves `cats` empty on purpose, so it is not a way to
smuggle a multi-level axis in flattened.

`FrameGroup::collapsed` is on the wire rather than left to the client because
it is a fact about the *view*, which only the server holds. `FrameGroup::cat`
travels so a client can echo it back in `ToggleGroup` without ever working out
which category a label came from — which slash-joined labels made impossible.

### `AxisFrame`: four accessors that are **not for a draw loop**

`item`, `label`, `shows_level` and `group_of` each scan `entries` from the
start, so asking them per position is quadratic in the frame length and, in
the TUI, **grows with the absolute scroll offset**. That defect was found
three times on improvise-anr9. The per-position forms survive for one-off
lookups only, and their two-line warnings are the thing standing between a
future renderer and a measured regression.

- `shows_level` is the worst of the four: it materializes **every** item on
  every call. It is deliberately not made cheaper, because a fast
  per-position form is an invitation to the loop `header_labels` exists to
  replace.
- `group_of` walks `entries` twice over, once to place `idx` and once
  backwards.

The one-pass forms a draw loop wants:

- **`header_labels(first_rendered)`** — every header label with suppression
  already applied, indexed `[data index][level]`, `""` where the label
  repeats. The suppression rule still has exactly one home (`fn shows`); this
  is `shows_level` applied in bulk, not a second copy of it.
- **`groups()`** — `group_of` for every position, in one pass.
- **`shares_ancestry(with)`** — the TUI's column-header underline: at the leaf
  level only the selected column matches, at a higher level every column under
  the same ancestor. There is deliberately **no** per-position form beside it,
  because one would be a second answer paid for per (column, level) — two
  frame scans apiece.

**`leaf_labels()` is not "the labels".** It is the innermost label of each
item: the single most specific name a position has, what a test or a one-line
summary calls a row by. A renderer reaching for it on a multi-level axis is
drawing the *wrong* header, not a shorter one.

**`first_rendered`** is the first data index actually on screen. That entry
always shows its full tuple, or a scrolled viewport loses its group context at
the top edge (improvise-jjx).

**`body_from(idx)`** drops the group header that owns the first drawn item: a
frame opening mid-group carries that header so `group_of` can answer for it,
but it is *above* the first drawn row and must not be painted as one. This is
the same cut `GridLayout::data_row_to_visual` has always made.

Two things about its argument, and the first of them **used to be the whole
story and was wrong**. It exists partly because the two front ends scroll
differently — a browser's frame is already windowed and passes `0`, the TUI's
covers the whole grid and passes its row offset (gotcha 44). But `idx` alone
cannot say whether the frame *leads the axis*, and at the top there is no
header "above" to drop: it is content, and a collapsed first group has no
other affordance. That is `AxisFrame::first` and improvise-0o6x — §3a.

**`group_of` answers membership**, and the paragraph that stood here said the
opposite: that it answers "nearest preceding header", deliberately, because
that is what the TUI had always painted, and that encoding an end boundary
would mean changing `AxisEntry` in `improvise-core` and was "filed rather than
smuggled into" improvise-anr9. All of that was true when written. **The filed
ticket is improvise-gd83 and it has landed** — `AxisEntry::GroupEnd` closes a
run, `groups()` clears on it, and the TUI's painted span changed with it. The
mechanism and its two emission arms are §3a.

That correction is here rather than only in §3a on purpose. This paragraph
forbade, in terms, the change §3a describes; a reader arriving at the stale
copy first would conclude the rule had been smuggled past its own prohibition.
When a fact is stated twice, changing it is a grep (gotcha 48) — and the two
copies being in *one file* is what made this worth saying out loud.

### The width rule has one home

`header_level_widths` (improvise-1125): per level, the widest label **in
display cells** plus a gap, clamped to `[MIN_ROW_HEADER_W, MAX_ROW_HEADER_W]`.
It lived twice before — inline in `src/ui/grid.rs::render_grid` and again in
`improvise-command::ui::viewport::compute_row_header_width` — and a browser
sizing its own row header would have been a third.

It takes an **iterator of borrowed tuples** rather than an `AxisFrame`
because its other caller holds a `GridLayout` and is on the keypress path
(reached from `App::cmd_context`); building a frame there to ask the question
would clone every row tuple on every key (raised by Copilot on PR #23).
`AxisFrame::header_widths` is the frame-shaped entry point, derived rather
than projected as a field because the frame is the whole input — nothing about
the model is needed, so a shared function cannot fall out of step with the
data the way a separately-sent field could.

### `GridCache` is viewport-indexed, and `GridExtent` is not

A cache position is a position within the *viewport*: the client does not know
the model's coordinates, and the server is free to change what a row means as
long as it says so.

`GridExtent` is how big the **whole** grid is, of which the frames are one
window (improvise-bpq2). It is the one fact a client needs to move its own
cursor: `row_frame.len()` is what this client was *sent*, so a client holding
only its window cannot tell "the last visible row" from "the last row" and
cannot clamp — a cursor clamped against the window stops at the bottom of the
screen. It is deliberately **not framed** by the frames, unlike `cells`,
`col_widths` and `totals`: it is the size of the thing they are a window
*onto*, so `fit_to_labels` must leave it alone.

For a client whose window covers the whole grid — the TUI, which builds its
cache at offsets zero — it *equals* the frame counts, and **that coincidence
is exactly what makes a derived version look correct there and fail in a
browser.** It is a named pair rather than two `usize` on `GridCache`, because
beside `row_frame`/`col_frame` two bare counts read as "how many rows are in
the frame", which is the confusion the field exists to remove.

`GridUpdate::Extent`'s batch position is **not** load-bearing the way
`RowFrame`-before-`Cells` is: it addresses no position, so it cannot overtake
or be overtaken. It is emitted first only because outermost-first reads better.

### `GridCache::totals` — empty means "no totals", not "not caught up"

Framed by `col_frame` exactly as `cells` and `col_widths` are, with one
asymmetry: an **empty** strip means this grid has no totals to draw (records
mode, or an empty grid) and is therefore *not* padded, where a non-empty one
is. Padding an empty one would draw a blank total row under a records-mode
grid that has none.

The emptiness is the server's answer rather than a client's re-derivation,
and the totals **must** be projected rather than client-derived: the sum runs
over *every* row including the ones this viewport has scrolled past, so a
client holding only its window could not compute it.

`page_coords` is framed by **nothing** — it names categories, not positions —
so it survives a reshape that drops every row and column. It carries Page
*and* Filter (`View::filtering_cats`, gotcha 27): both restrict what is
visible, and the bar states what is being looked at, not what the user may
page through.

### `CategoryTreeUpdate::Items` and `::Axes` have no producer, deliberately

`document_projections` only ever sends `Categories(..)`, which replaces the
whole panel. The other two arms are **derived rather than invented**: the
effects that move a category tree come in three shapes — the list reorders
(`AddCategory`/`RemoveCategory`), one category's items move (`AddItem`/
`RemoveItem`), several axes move at once (`SetAxis`, and `CycleAxis` through
it) — and `doctrine(derive_the_enum_from_the_effects)` is the same recipe that
built `ModelCommand`. An arm the derivation produces is not speculation just
because the producer has not reached for it.

What the producer reaches for instead is the coarse arm, on purpose:
`category_tree_of` walks every category once, the panel is small, and
`Dirty::of` cannot say *which* category moved anyway — an `EffectKind` says
that a batch changed the tree, never which part, exactly as it cannot say
which records a `CellData` batch wrote (gotcha 40). Emitting `Items`/`Axes`
therefore needs the tree **observed and diffed**, the way `document_update`
observes the title bar, and that is a bandwidth optimisation for a widget that
costs a few hundred bytes. It is not worth doing until category-tree traffic
is measured to matter.

The contrast with the deleted `Invalidated` is the point: these are *unused*,
and `Invalidated` was *redundant* — its meaning already lived in running code.
Unused-but-derived earns a note; redundant earns a deletion.

### The fold is not commutative — three rules in `apply`

**(a) A `Cells` update that overtakes its frames is dropped, not guessed at.**
`fit_to_labels` truncates to the frames it has. A client must not reorder the
stream.

**(b) A frame change that *renames* a position blanks the cell under it.**
`fit_to_labels` preserves **by position**, which is only right where the label
did not change, so `apply` calls `invalidate_relabelled` itself rather than
trusting a producer to declare it. It blanks the totals too, because they are
contents and a stale sum under fresh cells is the one number a user takes at
face value.

**There used to be a `GridUpdate::Invalidated` arm** meaning "contents stale,
frame unchanged", and it is **deleted** (improvise-n89z). It never had a
producer: `grid_updates` diffs, so it always knows *which* cells moved and
sends `Cells`, and `GridCache::seed` compacts. There is no state in which a
server knows the contents are stale and not which ones — and if there ever
were, the answer is a fresh `Snapshot` through `rebase`, not a blanking the
client cannot act on. Meanwhile its stated meaning had migrated into running
code: `invalidate_relabelled` blanks exactly what a reframing invalidates,
totals included. So it was **redundant**, not merely unused, and three
documents described it as load-bearing, which is worse than silence — a reader
reasoning about the fold's guarantees assumed something produced it.
`the_retired_invalidated_spelling_does_not_parse` keeps it from returning as a
serde alias.

**(c) Every arm that touches a frame *or* the widths re-fits.** A renderer
zips widths with labels, and a length mismatch indexes off the end. Fitting on
the frame arms alone is what let a late `ColWidths` put the mismatch straight
back: a short update keeps each unheard-of column at its own widest level
label until `ColWidths` catches up, and a long one is dropped as having
overtaken the frame that names it, exactly as (a) holds `Cells`.

The fallback width is measured in **display cells**, the same unit
`header_widths` and the authoritative `ColWidths` use: `chars().count()` would
draw `日本` two cells wide where it needs four, so a cache caught between
`ColFrame` and `ColWidths` would render the new column too narrow. The
materialization inside `fit_to_labels` is deliberate — `AxisFrame::item`
scans, so asking it per column would make a re-fit quadratic.

### `invalidate_relabelled` — a `cats` change re-identifies *everything*

**A cell's identity is `cats` zipped with its item tuple, so a change of
`cats` re-identifies every position at once** — even the positions whose
labels are byte-identical. `Region = [North]` becoming `Department = [North]`
leaves `items` equal and names a different cell, so the tuples alone cannot
answer this and every surviving position is stale.

The sharpest half is invisible: a preserved `CellDisplay` carries an editable
`CellId::Record` (ADR 002), so a client would go on offering an edit that
addresses the record the **old** coordinate named — a misdirected write, in
the same family as gotcha 18's drill snapshot, and one no rendering shows.

Otherwise the comparison is on the **item tuples**, not the entries: a group
header appearing or collapsing changes the frame's shape without renaming any
surviving position, and blanking on that would throw away cells the very next
`Cells` update would have to resend.

Two asymmetries about totals:

- A relabelled **column** drops its total (improvise-hkt6): the total under it
  is the sum of the old column. A relabelled **row** does not, because a total
  spans every row and is not framed by any one of them.
- A **recategorization of either axis** blanks every total. A column total is
  a sum over the rows, so re-identifying the rows leaves a number that answers
  coordinates the grid no longer has.

This is what obliges the *producer* to diff the totals against the frame the
label updates will leave rather than against the mirror they change: a column
renamed while its total stayed the same number is blanked here, and a producer
comparing `mirror.totals` would find them equal and send nothing.
`grid_updates` compares `framed.totals` for exactly that reason. The blanking
stays anyway, because rule (b) exists to stop `apply` trusting a producer to
remember — **the rule lives on both sides or on neither.**

`LabelAxis` is private so the row and column cases share one invalidation
rule rather than two copies that can disagree.

### Bootstrap is a compaction, not a replay

A server does not replay history to a late client — it holds the current state
and expresses it as the same updates the steady stream carries, so bootstrap
is not a second code path and there is no whole-state shape that could
disagree with the incremental one. The property that earns it is
`GridCache::folded(&cache.seed()) == *cache`, and it is the **ordering** that
earns it: the frames frame the cells, so they go first.

`Snapshot { view, seed }` is the only thing on the wire that is not an event,
and `view` is the one point at which `ViewState` is serialized (improvise-q08).

Note the fold tests: asserting `fold(prefix) + fold(rest) == fold(whole)` is
**vacuous** — it is the definition of a left fold — so the tests that earn
their place are the order-sensitivity one and the compaction-equivalence one
(`doctrine(fold_tests_must_test_order_not_the_axiom)`).

### `CategoryTreeCache` carries every category, `_`-prefixed included

improvise-vjms: the TUI panel has always listed them, and a browser panel that
quietly did not would be a second, divergent answer to "what are the
categories". So the `_`-prefixed convention does reach the client — it is
presentation, and both ends render the same rows from this one source.

**The trap is `_Measure`, whose items are derived**: explicit items ∪ formula
targets (gotcha 7). Whoever builds these rows must go through
`Model::effective_item_names`; reading `category("_Measure").items` compiles,
looks right, and silently omits every formula target.

Three mutations reach this panel because the effects are three *shapes*:
adding or removing a category reorders the whole list, adding or removing an
item touches one category, and a transpose moves several axes at once without
touching membership. Which categories are *expanded* is
`ViewState::expanded_cats`, per-client, so the flattening is a client-side
concern and does not belong on the wire.

`FormulaCache` and `ViewListCache` take one whole-list update, because add and
delete are the only effects that touch them and both are cheap to send whole.
Which view is **active** is not in `ViewListCache`: that is
`ViewState::active_view`, carried by `Command::SwitchView`, because it is
per-client (improvise-8uz). Likewise which tile the cursor is on is
`ViewState::tile_cat_idx`.

### `WizardCache` has a shape and deliberately **no** `Projection`

improvise-764, and that absence is the ticket's answer to "where does the
wizard state live". A `Projection` is broadcast to every connected client's
widget, which is right exactly when the change is addressed to *no one*
session. A half-open import dialogue is the opposite: it belongs to precisely
the session that opened it. That is already settled doctrine elsewhere —
`ImportWizard` lives on `App` and not on `ViewState`, and `AcceptWizardModel`
was removed from `ModelCommand` for this same reason (improvise-tom1) after B
was shown swapping the document out of a dialogue B never opened. Putting the
wizard on the broadcast stream would have re-created that bug on the
*rendering* side: every client drawing a dialogue one of them opened.

So it is a cache in shape and a **local render model** in fact, built from the
authoritative `App` by the host that holds the wizard. **A cache without a
`Projection` is the shape session-local residue takes when it still has to be
drawn by two different front ends.** It lives here rather than in
`improvise-command` for the `flatten_cat_tree` reason: the browser client
depends on `improvise-protocol` alone, and when it grows a wizard it must draw
*these* rows, not a second derivation. When multi-client import arrives it
wants the addressed form, which is where ADR 001 layer 2 goes anyway.

Every field is already render-ready — the widget that used to build these
reached through `ImportWizard` into `ImportPipeline`, `FieldKind`,
`DateComponent` and a whole `Workbook`; none of those cross now. Two
substitutions are made *here* so both ends spell them the same way: an
undetected date format reads `"?"`, and the root array path reads `"(root)"`
rather than empty. `WizardProposal::kind_label` is carried rather than
re-derived from `kind`, so the two ends cannot disagree about what "Measure
(numeric)" is called.

`WizardStepKind` mirrors `improvise_io::import::WizardStep`, spelled again
rather than re-exported, because this crate must not depend on `improvise-io`
(the wizard is an io type, gotcha 30) and a client that draws the wizard must
still be able to name the step it is on. `WizardFieldKind` is the semantic
half of a colour decision — the terminal mapping lives in `draw.rs`, exactly
as `AxisColor`/`axis_fg` does (gotcha 26).

### `Projection` carries no multi-widget variant

The envelope a widget subscribes by: it folds the payload of the variant that
names it and ignores the rest. There is deliberately no variant carrying
several widgets' updates together — that would be the aggregate cache in
another form.

Nothing is defined for the help overlay: its content is static and
`help_page` is already in `ViewState`.

---

## §3a. The frame's group boundaries and its position in the axis

Two facts `AxisFrame` gained after `improvise-anr9`, both about group runs.

**`FrameEntry::GroupEnd` closes a run.** `group_of` used to answer "nearest
preceding header", which is not membership: `expand_category` emitted a header
on *entering* a group and nothing on leaving one, so an ungrouped item after a
grouped run inherited it (`improvise-gd83`). The §3 paragraph that recorded the
old rule — and forbade this change — is corrected there, not merely superseded
here. `AxisEntry::GroupEnd` is
the boundary, carried onto the wire as `FrameEntry::GroupEnd`; `groups()` clears
`current` on it and `group_of` stops walking. It is emitted only on
`Some -> None`, never between two groups — the next header already ends the
previous run — and at the end of an expansion whose last item was grouped, which
is the across-prefix arm `cross_product` creates.

Nothing draws a `GroupEnd`. Both front ends skip it and it consumes no data
index, so it is invisible except through `group_of`/`groups`.

**`AxisFrame::first` is the absolute data index of the frame's first item.** The
windowing rule carries the nearest header *above* a scrolled window so
`group_of` can answer, and `body_from` drops it on the way to the screen. At the
top of an axis there is no "above", so that same leading header is content — a
collapsed first group has no other affordance (`improvise-0o6x`). `idx` alone
cannot tell the two apart, because the browser's frame is already windowed and
always passes `0`; `first + idx == 0` can.

The TUI builds over the whole grid so `first` is always `0` there, and the
browser's comes from the projected window. A frame built by hand in a test must
set it, which is why it is a plain field rather than derived.

It carries `#[serde(default)]`, and **that is a defect rather than a decision**
(improvise-1wl0): `first: 0` is not an absence but the claim "this frame leads
the axis", which is the claim `body_from` acts on — so a frame that loses the
field deserializes as leading. No skew ships today, both ends being one
workspace at one commit. Same argument as `Basis` having no `Default`.

**`group_runs` / `group_run_heads` are the coalescing rule's one home.** The TUI
and `render.rs::col_groups` each coalesced adjacent columns sharing a group,
kept in step by a comment (`improvise-8qlr`). Runs coalesce by group **name**,
so two adjacent runs under two different headers of the same name read as one —
that is what both ends did before and is preserved deliberately, because
changing the rule in the commit that moves it would leave the agreement test
unable to tell "both ends agree" from "both ends changed together".

`FrameGroup` carries `cat` and could fix it, and **a single home reads as
decided** — which is the new risk and why it is filed as improvise-h0iv rather
than left as a note. The TUI's one
divergence is that it labels its first *visible* column even mid-run, so a
scrolled grid does not draw an unlabelled group line.

## 4. `frame.rs` — one envelope pair, two deployments

### The framing adds as little as it can get away with

`doctrine(derive_the_enum_from_the_effects)`: inventing wire variants ahead of
the mutations that need them produces a protocol nobody can implement.

### There were three pairs for two deployments (improvise-xks6)

The socket's server side, a hand-kept **mirror** of it in the browser bundle,
and a third pair written for the worker (improvise-tm6) before the projection
architecture landed. The question that had to be answered before any of it
moved was whether the **worker** and the **socket** want the same vocabulary.
They do, and the test applied to each difference was whether the *argument*
for it names the thing they differ in. None did — every difference was a
**date** rather than a decision:

- **`Viewport` is deployment-independent.** The extent is the one session
  input no `Command` carries by construction: it is a fact about a terminal or
  a browser window, it is not in `ViewState`, and no effect produces it, so no
  derivation reaches it. A worker hosting the same `Sessions` owes
  `set_extent` the same answer. It is the **handshake** on both, because a
  `Snapshot` seeds the *visible* cells — one built at extent zero is an empty
  grid the client would immediately have to ask again for.
- **`Key` is deployment-independent too.** A keymap binding names an *intent*
  resolved against a `CmdContext` a thin client does not hold (gotcha 38),
  which says nothing about what the bytes travel over. The socket lacked the
  variant because key forwarding had never been built on it — a gap
  (improvise-bpq2), not a design.
- **`Commands(Vec<_>)` batches where a singleton cannot.** A fan-out must
  arrive whole and in sequence, because a `GridUpdate::Cells` that overtakes
  its frames is *dropped*, not replayed. That is a property of the **fold**,
  not of the transport: an in-process `postMessage` interleaves exactly as a
  socket does. `Commands(vec![c])` expresses everything a `Command(c)` variant
  could.

The worker pair was not merely different but **incoherent by omission**:
written before ADR 001, it could carry `Command::Model { basis, .. }` and had
no `Rejected`, so a client speaking it composed a claim that could never be
answered. **That incoherence — not the difference — is the tell for
staleness.**

### The mirror is gone, and so are the two tests that held it honest

That deletion was the ticket's measure of success.
`the_socket_framing_matches_the_server` round-tripped hand-listed fixtures
through the other crate's types to catch a **rename**;
`every_server_variant_is_one_this_crate_mirrors` matched exhaustively to catch
a **variant added on the server and never mirrored**. With one definition both
are **type identity**: a rename is a compile error at every call site in both
crates, and the un-mirrored variant is not a constructible state. That is
stronger than either test, and it is the shape to insist on — **if a
consolidation leaves one of its compatibility tests alive, the consolidation
is not finished**
(`doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished)`).

What survives is `the_retired_spellings_do_not_parse`, aimed at the one thing
still possible; see `context/test-evidence/protocol.md`.

### `ClientFrame::Commands` — the frame is the unit of atomicity

Not the command (ADR 001, improvise-955n). The host answers for *every*
command in the frame before applying any, so a frame is never applied
partially **because of a refusal**. It used to apply in order and abandon at
the first rejection, which left a hole ADR 001's "never applied, not even
partially" does not have.

**The frame states one basis**, and it is the only claim a client can
construct: a basis is published between batches and never during one, so no
client can hold one describing the document as it would be half-way through
its own frame. Commands then run in order, each against what its predecessor
left, and data dependence between them is expected — a chain may create a
record and then write it.

**But only two of the three tiers are answered once.**
`document_generation` and `layout_version` describe the *document*, so
answering them on the frame's first mutation is right. The **record tier is
asked of every mutation**, because which records are at stake is a property of
the command rather than of the frame — skipping it for later commands let one
client's chain overwrite a record another had moved, silently. The exemption
that keeps data-dependent chains working is narrower than "later commands are
not checked": a record that **neither resolves nor is claimed** is one the
frame is about to create, and only that combination is exempt. A record that
resolves is answered for however the claim is written. `CheckedBatch` in
`improvise-command` carries the derivation.

**All-or-nothing is the contract and clause 4 is not yet delivered.** That is
the other way a frame stops half-way, and it is not a refusal: a chain whose
later command *fails at apply time* leaves its predecessors applied, because
`App::apply_effects` aborts **without undoing** (gotcha 21 — an abort is not a
rollback).

### `ClientFrame::Save` is a request, not a `Command`

improvise-368h. It carries **no path**, because a client cannot see the host's
storage: `effect::Save` writes to *this host's* `file_path` through *this
host's* `Storage` (gotcha 2), and which document a host is hosting is the
host's own fact. A client naming a path would be naming a namespace it cannot
read — the same mistake `ModelCommand::SetCell` avoids by taking a surrogate
rather than a `CellKey`.

**It is a frame and not a `Command`, and the reason is atomicity.** It began
as a `Command`, which put a *runtime-fallible* operation inside a batch
`Commands` guarantees is applied whole or not at all — so `[Save, SetCell]`
reported a failed write and then applied the edit anyway, and a client reading
"refused" could not tell which. Saving also fails the test every `Command`
passes: it mutates no shared state and no client's slice, so `reduce_view` has
nothing to fold and `Checked` has no basis to answer for. Here it cannot be
composed with a mutation at all — **the batching question stops being a rule
and becomes unconstructible** — and it sits beside `Viewport`, the other
session input no `Command` carries.

Success is silent: the document did not move, so no widget is dirty and nobody
else is owed anything.

### `ClientFrame::Key` — and a correction

The doc used to say "the host runs it through the keymap against the
authoritative `App`". **It does not.** `Host::handle` answers this arm with an
explicit empty vec, because a key resolved on the host moves state no client
can hear (`a_key_resolved_on_the_host_moves_state_no_client_can_hear`): the
projection stream carries nothing of the host's own `ViewState`, so host-side
resolution *diverges*. improvise-bpq2 closes that by **avoiding** it — the
browser resolves keys against the shared keymap (§6) — so an upstream key is a
**black hole, not a slow path**, and every `KeyOutcome::Upstream` names a
binding that does nothing at all in a browser. The variant is kept because the
list of keys that still need the host is named in
`improvise-wasm-client/src/keys.rs`, so closing one has to come there and say
so.

It carries `(KeyCode, KeyModifiers)` rather than a `KeyEvent` because
`KeyEvent` is not `Serialize` — the same pair `Command::SetTransientPrefix`
already puts on the wire.

### `ServerFrame` has three variants because `Sessions::apply` has three cases

`Applied::Diff`, `Applied::Rebased`, `Applied::Rejected` (gotcha 39).

`Snapshot` is **boxed**: it carries a whole `ViewState` plus the seed that
redraws the document, and every `Commands` frame would otherwise be allocated
at that size for a variant sent once per connection. Serde sees through the
box, so the JSON is unchanged. It is sent again to *every* client whenever the
document is replaced, because a client's `cursors` are keyed by the outgoing
document's view names and only a fresh snapshot replaces them (gotcha 24).

`ServerFrame::Commands` carries both of the things a client folds, because on
the wire they are the same thing: a `Command::Project` is a widget update, and
any other `Command` is a peer's accepted move that this client's own view
slice must fold too (gotcha 36). Order is load-bearing, so a transport must
deliver a batch whole and in sequence.

`Rejected` is addressed to **the asker alone** — nothing happened, so nobody
else is owed anything — and it carries no new state, because the client
already holds what is current through the projections it has been folding all
along. That is what makes rejection cheap enough to be a *normal outcome*
rather than an error.

---

## 5. `basis.rs` — what a batch was composed against

### The problem is not ordering

The server already serialises every write — one `App`, one `apply_effects` —
so there is a total order and nothing here is about ordering. What was missing
is noticing that a client composed an edit against a **picture of the document
that has since moved**: the same stale-basis shape as the cursor under a
reshaped grid (gotcha 24) and the session mirror after a document swap (gotcha
39), one level up.

### Three tiers, and the tiering is the whole economy

| tier | moved by | a batch is stale if |
|---|---|---|
| `document_generation` | a `WholeWorkbook` effect | it moved at all |
| `layout_version` | an observed change to any view's drawn shape | it moved at all |
| `records` | a `CellData` effect on that record | any record the batch names moved |

A cell edit is stale when the **layout** moved, even though no record it names
was touched, because the shape its keys hang off changed underneath it. That
is ADR 001's class 2 — A removes the category `Region` while B commits an edit
keyed by `Region=East` — and it is **corruption** rather than a lost
keystroke. Detecting it falls out of the tiering with no lock anywhere: a
cell-level lock would not have covered it, because holding
`Region=East × Revenue` does not stop anyone deleting `Region`.

### The client understands none of this

A `Basis` is three opaque tokens — nothing in it is a structure to interpret,
the same discipline as the cell surrogate it is keyed by (ADR 002). The server
publishes the current one as a `Projection`, the client keeps it in a
`BasisCache` and hands back `claim()` when it composes a write.

### `Basis` has no `Default` and no public constructor

A zero-valued basis is not "no claim", it is the claim that **the document is
fresh** — which in a brand-new `App` is true, so a default would be a
*forgeable bypass* rather than an absence. `BasisCache::claim` is the only
door a client has, and it returns `None` until the server has published one.

Note what that does and does not buy. `Basis` derives `Deserialize` because it
must cross the wire, and its fields are public, so **a hand-rolled client can
state any tiers it likes**. This is an *anti-staleness coordination check, not
a security boundary*: it closes **omission**, not **invention**, and nothing
here tries to close invention, because a client that forges a current basis is
indistinguishable from one genuinely caught up. "The only constructor" is a
statement about clients written against this crate, which is still worth
having — it makes the honest path the easy one.

There is deliberately **no flag that skips any of this**, because "a mechanism
whose only purpose is to violate the invariant is not a feature, it is the
invariant deleted with extra steps". A *force* re-composes the same intent
against the current basis and submits a fresh batch; it never applies a stale
one.

### `claim` omits rather than invents

A record the cache has never heard of is **left out**, not defaulted to zero.
Defaulting would be a claim the client cannot support, and the server would
read it as "untouched" — the exact forged-basis case `RecordUnstated` exists
to catch.

### The publication is what ADR 001 omitted

The ADR says "a batch carries the basis it was composed against" and never
says how a client comes to know one; nothing in the projection stream carried
any of the three tiers, so **the check as written was satisfiable only by
forging**. That is the one place that document met the code and was wrong.
`Projection::Basis` + `BasisCache` close it.

It is folded like any other widget (improvise-rkeq) — not a widget, nothing
draws it, but it subscribes on exactly the same terms, and the alternative was
a second server→client channel with its own ordering rules for a payload that
changes at precisely the moments a projection already does. The update
replaces wholesale, as `Projection::Formulas` does, so "has it changed" and
"send it" collapse into one decision.

**It is emitted *after* the grid updates in a batch**, because the counters
describe the cells those updates carry: a basis arriving first would let a
client claim a version for a value it had not been shown — the mirror image of
the fold's frame-before-cells rule.

### Which records are checked is the server's decision

`reduce.rs::records_named` in `improvise-command`, an exhaustive match with
one or-pattern for the variants that name no record, so a new record-writing
variant fails the build. Reading the list off the *client's* claim would be a
**force by omission**: the record tier skipped, with no flag to remove and
nothing in the message saying so.

### `published()` takes a `BTreeMap`

So the record list is deduplicated and in a stable order. The server diffs the
published basis against what it last sent this client, and a list whose order
followed grid traversal would report a change every time a row moved.

### `Rejection` keeps structural and data staleness apart

Which is the whole reason ADR 002 put a maintained `RecordHash` index in
`DataStore`: a regenerate-on-demand scheme could not tell a record that had
scrolled out of view from one that no longer existed.

- **`RecordMoved`** is class 1. Somebody wrote the record since this client
  read it. Force is coherent and should be one keystroke: the user has seen
  the other value and chooses to overwrite it.
- **`RecordGone`** and **`LayoutMoved`** are class 2. There is nothing
  coherent to force — the key names a coordinate that no longer exists, and
  applying anyway is exactly the ghost-coordinate corruption this check exists
  to prevent. **Force never creates structure**: re-instating a category
  somebody deleted so an edit can land is a larger intent than the user
  expressed and must be an explicit action. What the UI owes here is what
  changed and the concrete alternatives, not a button.
- **`RecordUnstated`** is a case of its own because "you lost a race" and "you
  were never in one" are different things to tell a user — and because naming
  it is what closes the force-by-omission hole. A well-formed client cannot
  produce it: it composes a write from a cell it is drawing, and the published
  basis covers every record its grid names.

This is also why the wasm client stores the `Rejection` itself rather than
collapsing it into `status_msg`: a string cannot carry *which* record and
*which* kind.

### Two classes live in one type

`Rejection` is a refusal of a **frame**, not of a command — since
improvise-368h a `ClientFrame::Save` the host cannot honour is answered here
too, and that is not a refused command at all.

1. **Staleness** (ADR 001) — `DocumentReplaced`, `LayoutMoved` and the three
   record variants. The only class where *force* means anything.
2. **A request the host cannot honour** — `NoDocumentPath` and `SaveFailed`
   (improvise-368h). Nothing went stale; there is nothing to re-compose.

They share this type rather than getting refusal channels of their own, for
the reason the type exists: a refusal is "nothing happened, here is why",
addressed to the asker alone, and a second channel would be a second set of
ordering and addressing rules for one idea. A **third class is coming and is
not here yet**: a transaction rolled back because a later command in a chain
could not be applied (clause 4 of the frame contract). Until rollback exists
there is nothing to report, because nothing is undone.

`NoDocumentPath` is decided **before** anything runs, by the same constructor
that answers for a basis, so a save that cannot land is refused rather than
attempted. What the asker should do about it differs by front end: a TUI
prompts for a path (improvise-lae), a browser worker whose document *is* its
storage entry never sees this at all. `SaveFailed` carries no message because
`Rejection` is `Copy` and an I/O error's text is not — the host keeps the text
in its own status line, and what crosses the wire is the one fact a client can
act on: the document it is editing is not on disk. **Reporting a failed write
as success is the thing this exists to stop.**

---

## 6. `keymap.rs` — one table, both ends

This used to live in `improvise-command`, where only the terminal could reach
it, and the browser client carried a hand-written classifier answering the
same question for the subset it could resolve. That is two definitions of one
vocabulary kept in step by a lockstep test over a hand-written list of keys —
and `doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished)`
says such a pair is one definition waiting to be made.

The move is the one gotcha 13 already anticipated:
`ViewState::transient_prefix` stores a prefix as an **address** rather than an
`Arc<Keymap>` precisely so `ViewState` could stay free of `improvise-command`
types while the keymap came the other way.

### The boundary that did not move

A lookup yields a command **name and arguments**. Turning that into something
that runs needs a `CmdContext` — a `Model`, a `GridLayout`, an `App` — which a
thin client does not have, so *intent → mutation* stays where it was:
`improvise-command` resolves a name through its `CmdRegistry` into `Effect`s,
and a browser client resolves the subset it can compose into `Command`s.

That is a better seam than the one it replaces. The drift risk used to be
"which key does what" — ~170 bindings, no direct test, invisible when wrong.
It is now "which command names can I execute", which is a list.

What stayed in `improvise-command`, and why each had to:

- `Keymap::dispatch` and `KeymapSet`, which pair this table with a
  `CmdRegistry` and return `Box<dyn Effect>`.
- `SetTransientPrefix`, which is an `Effect` — it writes
  `ViewState::transient_prefix`, and `Effect` is the command layer's trait.

The keymap's own tests live with `dispatch` in
`improvise-command/src/command/keymap.rs`, for the same reason: they need a
registry to check a bound name against.

### `ModeKey` and `AppMode` are two different enumerations

They happen to be the same size (17). `SearchMode` is a `ModeKey` and not an
`AppMode` — it is Normal plus `search_mode: bool`; `Quit` is an `AppMode` with
no keymap. **Do not "fix" one count to match the other.**
`ModeKey::from_app_mode` is exhaustive on purpose: a new `AppMode` without a
keymap silently swallows every keypress, so the compiler must flag it.

### Lookup fallback order

`exact(key, mods)` → `Char` with `NONE` (shift is implicit in the char) →
`AnyChar` → `Any` → parent. `Keymap::with_parent` is Emacs-style inheritance,
and it is what lets `RecordsNormal` reach Normal's `g`/`y`/`Z` prefixes.

`Keymaps::prefix_keymap` deliberately goes through `lookup`, which walks
parents, for exactly that reason. Resolution assumes prefixes are **flat**;
`prefix_keymaps_are_flat` fails the build if a nested one is added.

### `TextEntry` — the spine, welded

Every text-entry mode has the same spine: characters append to one named
buffer, Backspace pops from it, Esc clears it before leaving. Only the buffer,
the exit mode and the commit keys differ. Building them through here means a
new text mode cannot accidentally type into one buffer while clearing another,
or drop the clear entirely — which would leave the next entry pre-filled with
the last one.

`TextEntry::new` takes the `AppMode` and reads the buffer name off its
`MinibufferConfig`, so the buffer the prompt describes and the buffer the keys
edit are the same string **by construction** rather than by agreement
(improvise-k8h) — the keymap never spells a buffer name.

`commit(key, cmd, args)` welds the command to its `clear-buffer` so no caller
can bind a commit without its clear (improvise-w3q). `rebind` exists for
exactly one case: CommandMode's Backspace, which exits the mode on an empty
`:` line instead of popping a character that isn't there.

**Eight `AppMode` variants carry a `MinibufferConfig`**, and `buffer_of`'s
callers are all eight. Seven are built by `TextEntry::new`; `RecordsEditing`
is built by `TextEntry::with_parent` off `Editing`'s map, so a count taken off
the `::new` call sites reads **seven** and is not the number of text-entry
modes. (See repo-map gotcha 11 — this exact count has already gone stale
once.)

`SearchMode` is hand-written on purpose and does **not** use `TextEntry`: it
has no commit key, and its query is owned by `exit-search-mode` rather than by
`clear-buffer`. "search" is not in the `buffers` map but its own `ViewState`
field, and `cmd::core::read_buffer`/`write_buffer` are the only code that
knows it (improvise-gdl).

Category and item add stay open after a commit, so Tab and Enter do the same
thing: file this one and start the next. `ItemAdd`'s keymap is built with an
empty category name because the category only shapes the prompt text, never
the buffer.

### `PanelKeymap`

The three panels share a spine — Esc/Tab leave for Normal, arrows and j/k move
that panel's cursor, every panel's toggle key is bound so focus can move
between them, and `:` opens command mode. The keys that act on the panel's
*contents* differ in **shape**, not just in command name (Category's `n` takes
an argument, View has no `a`, Formula has no Enter), so they arrive through
chained methods rather than a fixed-arity signature (improvise-4pg).
`delete()` binds `d` and Delete together so a panel cannot offer one without
the other.

`bind_panel_toggles` is called by `PanelKeymap::new` *and* by Normal, so a new
panel reaches all four keymaps from one `Panel::ALL` entry.

### Normal-mode bindings worth a note

`i`/`a` pass their target editing mode as an **argument** to `edit-or-drill`,
so the command itself stays mode-agnostic; `RecordsNormal` overrides just
those two bindings to say `records-editing`. Ctrl-S saves to the known path
and Ctrl-W asks for one — the pair a user with no file path needs, and what
the "No file path" status message points at (improvise-lae).

---

## 7. `viewmodel.rs` — the residue between a cache and a renderer

improvise-edp asked for a ViewModel *layer*, a `SurfaceViewModel` paired with
every `SurfaceCache`. **Most of that layer turned out not to exist**: after
improvise-35e each widget already takes exactly one cache plus the mode, and a
cache built per-widget is already render-shaped, so there is nothing left to
adapt. What this module holds is the residue — derivations genuinely *between*
a cache and a renderer, because they mix a cache with per-client `ViewState`.

Today that is exactly one: `flatten_cat_tree`. It lives here rather than in
`improvise-command` because two ends need it and only one of them can reach
that crate — the browser client depends on `improvise-protocol` alone
(deliberately; see its `Cargo.toml`), and `move-panel-cursor` walks this
flattening, so resolving that key client-side (improvise-bpq2) would mean
re-deriving it. **Two derivations of one flattening is how the two ends
drift.**

`CatTreeEntry` carries the axis outright, so a renderer needs neither a `View`
nor the cache the entry came from: the entry list *is* what the panel draws.
`expanded` is `ViewState::expanded_cats` — per-client, which is why this is
derived here and not sent — and the index into the result is
`ViewState::cat_panel_cursor`.

---

## 8. `key.rs`

These mirror the subset of the terminal backend's key API the command, keymap
and effect layers actually use, so those layers carry no terminal-backend
dependency. Variant names match crossterm's so call sites only need an import
change. The only place both type families may appear is the TUI boundary
(`src/draw.rs`), which converts incoming backend events into these before
calling `App::handle_key`.

`KeyCode::Null` stands in for "no key" (headless command execution) and for
any backend key code this crate does not model. `KeyEvent` is **not**
`Serialize` — `ClientFrame::Key` and `Command::SetTransientPrefix` both carry
the `(KeyCode, KeyModifiers)` pair instead.

---

## 9. Corrections made while relocating this prose (2026-09-20)

Four comments in this crate were **wrong about the code** and were fixed
rather than moved. Recorded because the campaign's own evidence is that a
stale argument reads exactly like a live one:

1. **`frame.rs`, `ClientFrame::Key`** said "the host runs it through the
   keymap against the authoritative `App`". `Host::handle` returns an empty
   vec for that arm. This is the fourth sibling of gotcha 48's "three comments
   in one range said *not built yet*" — improvise-bpq2 moved resolution to the
   client and updated one copy of the argument, not all of them.
2. **`reduce.rs`, `every_command_round_trips_through_json`** said the model
   half brings "four payload types the view half never carried — `CellKey`,
   `CellValue`, `Axis` and `PathBuf`". `ModelCommand` carries no `CellKey` at
   all since ADR 002 (`SetCell` takes a `RecordCell`), and `CellValue` *is* in
   the view half, as `Command::SetYanked`.
3. **`render.rs`, `identified_grid`** carried three paragraphs of doc that
   describe a *different* test — "improvise-hkt6 … three columns and a rename
   in the middle" is `a_relabelled_column_drops_its_total`, which had no doc
   of its own, while `identified_grid` is a two-column fixture. The paragraphs
   had been merged onto the wrong item.
4. **`keymap.rs`, `buffer_of`** said "the seven modes that carry a
   `MinibufferConfig`". Eight do, since `SavePrompt` (improvise-lae); seven is
   the number of `TextEntry::new` call sites, which is the exact confusion
   repo-map gotcha 11 already warns about.

Also stale and corrected, without being wrong enough to list above:
`key.rs`'s module doc called these "crate-local key types for the command
layer" — they are the protocol's, and both front ends use them.


**`records_named` lives here** (moved from `improvise-command::ui::reduce` by
the review of PR #50). It is `&ModelCommand -> Vec<RecordHash>` with no `App`
in it, and both ends need the same answer: the server to decide which records
to check, a client to decide which to claim. Two copies made the client's half
untestable — `lockstep.rs` restates the basis against its twin host, so it
compares the server's answer with itself. One home makes the claim right by
construction, and the exhaustive match is the guard it always was: a new
record-writing variant fails the build.

---

## §8 `help.rs` — where UI strings live relative to a wire enum

Three tickets asked one question three times — improvise-x7sw (which-key hints
have no protocol home), improvise-ktv1 (the browser has no help overlay) and
improvise-k099 (`AppMode::hint_text`/`label` put terminal UI strings on a serde
enum). Answering it three times is the disease. The answer:

**A UI string is keyed by a command name, never by a key, and never hangs off
the enum that crosses the wire.** `AppMode::label` and `AppMode::hint_text` are
gone; `help::mode_label` and `help::hint_line` replace them. The enum a client
deserializes now carries no English at all.

**And wherever a string names a key, the key is looked up rather than spelled.**
`Hint { keys, command, caption }` is the unit: `keys` come off
`Keymaps::default_keymaps()`, `command` is the semantic value a localized or
non-terminal front end keys off, and `caption` is the default English — exactly
the `AxisColor`/`draw.rs::axis_fg` shape, with the decision shared and only the
last translation local (`invariant(semantic_palette_at_the_core_boundary)`).

### What that bought, and what it cost

It **deleted** `every_hint_key_resolves_in_its_mode` and its 60-line tokenizer.
That test existed to hold a hand-written string honest against the keymap; the
string is derived now, so the property is true by construction. A consolidation
that keeps its compatibility test is unfinished
(`doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished)`),
and this is the deletion that measures this one. What replaced it,
`every_advertised_hint_names_a_binding_that_exists`, checks the *other*
direction — a mode advertising a command nothing binds — which was never
checkable before.

It also deleted `Keymap::binding_hints`: `help::which_key` is the one walker,
and the binding dump reads it too rather than a second one.

The cost is that the hints changed shape. They are longer, they name arrow keys
beside `hjkl`, and two sub-lists in the help pages lost their visual indent.
That is the price of the keys being true.

### The three rules the rendering follows

1. `hint_line` **drops chorded keys** — any key held with a modifier beyond
   shift, asked of the **modifiers** and never of the label (improvise-thpe).
   `Hint::keys` is `(KeyCode, KeyModifiers)` and `compact` takes the pairs, so
   the string it used to parse is not in scope to parse; `Hint::labels` and the
   help pages format last, through the one spelling in `keymap::key_label`.
   `T` advertises
   tile select; its four Ctrl-arrow aliases would push the rest of the line off
   the screen and teach nobody anything. A client wanting all of them reads
   `hints()`, which keeps them.
2. It **runs single-character keys together** (`hjkl`) and slashes the rest
   (`Esc/Tab`), which is the idiom the hand-written hints already used.
3. A help-page row whose command resolves to **no keys is dropped**, so a page
   can never advertise a key that does not exist. `keys()` returning `Option`
   is what makes that unrepresentable rather than validated.

### What is *not* derived, and why

**The wizard's.** `AppMode::ImportWizard`'s whole keymap is one `Any` binding
into `HandleWizardKey`, which decides per step inside the command — so there is
nothing in the table to look up, and its hint is a hand-written tail. That is a
real hole and it is where it is visible, not papered over: a keymap cannot
describe keys a command resolves privately.

**`gg`, `yy`, `ZZ` and the ex-commands.** A prefix sequence is two addresses and
not one binding (gotcha 13), and `:q`/`:w` are parsed text rather than keys.
Both are `HelpLine::Literal`, which says out loud that the row is spelled rather
than derived.

**The captions.** `i:edit` where `i` entered records mode would still pass every
test here. A caption is English beside a command name and only a reader judges
it — the same limit gotcha 14 recorded for the old hint test.

### The browser half

`RenderModel` carries `help`, `help_page` and `help_titles`, and an **empty
`help` is what says the overlay is closed** — the page asks no question about
the mode, the same shape `col_groups` uses for "no groups". `web/app.js` paints
rows it does not author; `src/ui/help.rs` keeps its ratatui styles and lost
~310 lines of content that is now shared. Neither end restates what the keys
are.