# Kill ring — framing (Arc 2, editing table stakes) — rev 3

pmacs has Emacs keybindings on a one-slot clipboard: `C-w`/`M-w`/`C-y`
cut/copy/paste through `EditorCore.clipboard_slot`, a single `Vec<u8>`.
Kill something, kill something else, and the first kill is gone. There
is no `C-k`, and `M-y` is unbound. This arc adds the real thing: kills
accumulate in a ring, consecutive kills append, `C-y` yanks the head,
`M-y` immediately after a yank cycles older entries.

Roadmap: `docs/roadmap-2026-07.md` Arc 2 ("real kill ring + `M-y`").

**Rev 2** rebuilt the design around per-frontend command boundaries
after review showed `dispatch_key` is not the only input path. **Rev 3**
closes the second review's blockers: pointer gestures join the boundary
table; the shared ring gets stable entry identities so per-frontend
state survives other frontends' mutations; and two shipped bugs the
review surfaced move into scope — **GPU `Ctrl-V` paste is silently
dropped for semantic frontends**, and inbound paste fires no
`buffer.after-edit` anywhere.

## Ground truth (scouted + twice review-verified; as of `4c4295d`)

Input paths that reach a buffer or move point — **only the first runs
Lua command bodies**:

1. **Round-tripped chords** (`dispatch_key`): every CTRL/ALT chord
   (`src/optimistic.rs:134-142`) — all kill/yank commands, both
   frontends — plus all TUI keys. Commands run via `Action::Run`
   (`src/editor.rs:707`) or the self-insert fallback (`:730`); the
   post-command revision check fires `buffer.after-edit` (`:739`).
2. **GPU optimistic edits**: bare typing, Enter/Tab, Backspace/Delete
   arrive as CRDT ops at `handle_remote_crdt_op` (`src/daemon.rs:1941`)
   — no command, no dispatch_key. (Fires `after-edit` itself.)
3. **Pointer gestures**: grid `Mouse` → `dispatch_mouse`
   (`src/editor.rs:1114`) and the semantic `Pointer` path (`:1253`)
   move the cursor and set/clear selections — **no command boundary**.
   Right-click additionally opens the context menu.
4. **Inbound OS paste**: `FrontendEvent::Paste` → `paste_inbound`
   (`editor_core.rs:2096`) — **but only on the grid path**
   (`apply_event`, `src/daemon.rs:2241`). The semantic input
   dispatcher **drops `Paste`** (`apply_semantic_input_event`,
   `src/daemon.rs:2200`, `_ => {}` with a "no grid-less effect yet"
   comment). pmacs-gpu always negotiates semantic render
   (`pmacs-gpu/src/attach.rs:259`), so **GPU `Ctrl-V` is a no-op
   today** — a shipped bug. Where paste *does* land (TUI bracketed
   paste), it fires **no `buffer.after-edit`** — a second shipped gap
   (LSP never sees pasted text). And the grid handler **trusts the
   client-supplied payload id**: it sets `core.active_frontend` from
   `Paste.frontend_id` rather than the dispatcher's authenticated
   `source` (`DispatcherEvent::FrontendEvent { source, event }`,
   `src/daemon.rs:1428`) — a third shipped gap: a forged payload id
   pastes into *another frontend's* active window.
5. **Context menu**: `menu_invoke_active` (`src/editor.rs:946`) calls
   `invoke_command` directly — no rotation, no post-command check.
6. **`M-x`**: the minibuffer shadow returns before the post-command
   check (`src/editor.rs:664`), so `M-x`-invoked editing commands also
   miss `after-edit` today.

Clipboard: `clipboard_slot` + `pending_clipboard: Option<(FrontendId,
Vec<u8>)>` (`editor_core.rs:213,219`); `InstanceSignal::Clipboard`
(v6-floor) goes **to the originating frontend only**
(`daemon.rs:949-956`); GPU writes arboard, TUI writes OSC 52. External
content is visible to the daemon only via path 4.

`buf:replace` (`mod.rs:1216`) uses the Lua buffer edit path
(intercepts, then `notify_buffer_edit_to_windows`, `mod.rs:1344`) and
queues a daemon-origin CRDT op — rotation needs **no protocol change**,
but intercepts may alter/reject the edit, so callers must verify the
applied text.

Frontend lifecycle: `SessionDetached` (`src/daemon.rs:1574`) already
prunes six per-frontend maps; anything new that is keyed by
`FrontendId` must join that cleanup, and Lua-side per-frontend tables
need a detach signal (none exists).

Nothing tracks the previous command; no per-command hook; `C-k`/`M-y`
unbound; `M-d`/`M-BS`/`C-BS`/`C-h`/`C-DEL` discard deleted bytes; no
Emacs mark; `ed.region/cursor/delete_region/goto_byte`, `buf:slice`,
`pmacs.frontend.id()` (reads `active_frontend`) all exist; no
`clipboard_get`/`clipboard_set`.

## Decisions

### Q#KR1 — Lua ring on a Rust command-boundary substrate

The ring, append policy, yank sessions, and commands live in
`builtin/runtime/killring.lua`. Rust grows: the command-boundary
substrate (Q#KR2), `ed.clipboard_set(bytes)` + `ed.clipboard_get()`,
the **semantic-paste fix** and the **after-edit delivery fix**
(Q#KR10), the detach cleanup + `frontend.detached` hook (Q#KR11), and
the module load line in `EditorState::new`. The ring table is
daemon-global (shared across frontends, like the Emacs daemon);
everything session-shaped is per-frontend and identity-checked against
the shared ring (Q#KR4/6/7).

### Q#KR2 — Per-frontend command boundaries; every input path updates them

`EditorCore.command_history: HashMap<FrontendId, CommandBoundary>`,
`CommandBoundary { this: Option<String>, last: Option<String> }`.
`ed.last_command()` reads the active frontend's entry. Two operations:
**`rotate(fid, name)`** (`last = this; this = Some(name)`) and
**`break_chain(fid)`** (`this = None` — the next rotation yields
`last = None`, failing every chain/session check).

The boundary table — one row per input path (rev 3 adds pointer
gestures and the unified paste route):

| path | site | operation |
|---|---|---|
| keybound command | `dispatch_key` `Action::Run` | `rotate(fid, name)` |
| typed char (round-trip) | self-insert fallback | `rotate(fid, "buffer.self-insert")` |
| unbound key | `dispatch_key` unbound arm | `break_chain(fid)` |
| GPU optimistic edit | `handle_remote_crdt_op` | `break_chain(source)` |
| **pointer gesture** | `dispatch_mouse` (grid) **and** the semantic `Pointer` handler — any press/drag/release that moves point or changes the selection; menu-opening right-click included | `break_chain(fid)` |
| inbound OS paste | the **unified** paste route (Q#KR10) | `break_chain(source)` — the **authenticated** id, never the payload's |
| menu item | `menu_invoke_active` | `rotate(fid, name)` |
| `M-x` accept | `pmacs.command.invoke_interactive` (new) | `rotate(fid, name)` |

Pointer scope note: scroll-wheel events that move only the viewport do
**not** break the chain (point is untouched); anything that relocates
the cursor or edits the selection does. Emacs behaves the same way
(`mwheel-scroll` preserves `last-command` chains; `mouse-set-point`
breaks them).

`invoke_interactive(name)` rotates then invokes; `editor.execute-
command`'s accept uses it. Plain `pmacs.command.invoke` stamps nothing
(public programmatic API). This preserves rev 2's Emacs-verified `M-x`
matrix: `C-k`→`M-x kill-line` no-append; `M-x kill-line`→`C-k` append;
`M-x` twice no-append.

### Q#KR3 — What feeds the ring (v1 command set)

Unchanged from rev 2: `C-w`/`M-w`/`C-y` bodies become ring-aware
(context menu inherits by name); new `C-k` `edit.kill-line` (chunked
`buf:slice` newline scan; at EOL kills the newline) and `M-y`
`edit.yank-pop`. **Deferred**: word kills — `M-d`, `M-BS`, `C-BS`,
`C-h`, `C-DEL` all share the discard-the-bytes deleters and keep plain
deleting until the Rust deleters return bytes.

### Q#KR4 — Append requires success **and** an unmoved head (stable ids)

Rev 2's per-frontend `last_kill_ok: bool` corrupts the shared ring
under interleaving (review blocker): A kills, B kills, A kills again —
A's flag is still true, so A appends onto **B's** entry.

So ring entries carry a **stable identity**: each push mints a
monotonically increasing `id`; entries are `{id, text}`. The
per-frontend kill state is **`last_kill_id`** (nil = no live kill
chain), and the append condition becomes:

> `ed.last_command()` is a kill command **and** this frontend's
> `last_kill_id` is non-nil **and** equals the current head's `id`.

A-kill/B-kill/A-kill: A's `last_kill_id` names A's entry, the head is
B's → **push fresh**, B's kill intact. A successful push/append sets
`last_kill_id = head.id`; every failed or no-op kill-family invocation
clears it (rev 2's success rule, carried forward). Appends keep the
entry's `id` (the entry is *extended*, not replaced — a same-frontend
chain keeps appending). The appended head re-syncs to the acting
frontend's OS clipboard.

### Q#KR5 — The ring

Entries `{id, text}`, most-recent first, shared. Cap default **60**;
`pmacs.killring.max([n])` validated as in rev 2 (**non-finite
rejected** — `NaN`, `math.huge`; ≥ 1; floored; **shrink trims
immediately**). Duplicate-of-head pushes collapse (no new id).
`pmacs.killring.list()` returns texts for introspection/tests.

### Q#KR6 — Yank: per-frontend sessions, snapshot + stable cursor

`C-y` (unchanged flow from rev 2, session shape corrected):
1. Slot check: `ed.clipboard_get()` non-empty and ≠ head text → push it
   (external content joins the ring).
2. Ring empty → `"kill ring empty"`, no session.
3. `start` = region lo or cursor; `ed.clipboard_set` if the slot
   differs; `ed.clipboard_paste()` (existing insert-over-region,
   `cursor = start + len`).
4. **Session (per `FrontendId`)**: `{buffer, start, end, entry_id,
   text}` — `text` is the snapshot actually inserted (rev 2 claimed to
   verify against it but never stored it — review catch), `entry_id`
   is the ring entry's stable id (an index would be shifted by any
   other frontend's push — review blocker). Created only on successful
   paste.

**OS clipboard scope** (unchanged, explicit): the ring is shared; OS
mirroring is local to the acting frontend — `pending_clipboard`'s
existing `(FrontendId, bytes)` shape, and the right privacy call for
frontends on different machines.

Named limitation (unchanged): an external copy is invisible until
pasted; `C-y` before any paste yanks the ring head. GPU `Ctrl-V`
covers the direct gesture — **and actually works after this PR**
(Q#KR10 fixes the semantic drop).

### Q#KR7 — Yank-pop: stable-id rotation, snapshot-verified

`M-y` is valid only when, for the acting frontend: (1) `last_command`
is `edit.paste`/`edit.yank-pop`; (2) a live session exists; (3) the
session's buffer is active; (4) `buf:slice(start, end) ==
session.text`. Any failure → refuse with status, drop nothing into the
buffer, **and create/keep no session** (a second invalid `M-y` cannot
ride the first's name-stamp).

When valid:
1. Locate `session.entry_id` in the ring; **absent (evicted or
   trimmed) → invalidate the session and refuse.** Otherwise step to
   the next-older entry, wrapping. Because the cursor is an id, another
   frontend pushing entries mid-session shifts positions but not
   identity — rotation continues from where this frontend actually was
   (Emacs's `kill-ring-yank-pointer` behavior; an integer index would
   silently re-yank the wrong entry — review blocker).
2. `buf:replace(start, end, entry.text)`, then verify by re-slice.
3. On match: `ed.goto_byte(start + #entry.text)`, update `end`,
   `entry_id`, `text`.
4. On mismatch (a buffer intercept altered the edit): **accepted
   post-hoc semantics, stated as a decision** — the interceptor's
   result is left in place, the session is dropped, and the status says
   so. Kill/yank inside intercepted (round-trip/REPL-prompt) buffers is
   niche; a preflight refusal would need a new Lua-visible intercept
   probe, which is not worth the seam in v1. (Review offered both
   options; this is the explicit choice of the simpler one.)

The OS slot is untouched by `M-y`; undo treats each rotation as a
normal edit.

### Q#KR8 — No mark in v1

Unchanged: CUA selections only; `C-SPC`/set-mark deferred; `C-w`
requires a selection.

### Q#KR9 — Module shape and loading

Unchanged from rev 2: `killring.lua` holds the ring, the per-frontend
tables (keyed by `pmacs.frontend.id()`), commands, and bindings;
`default.lua` bodies delegate at invoke time; loaded explicitly in
`EditorState::new`.

### Q#KR10 — Unified paste + after-edit delivery (two shipped bugs, in scope)

**(a) Semantic paste, on the authenticated source.**
`FrontendEvent::Paste` is handled only in the grid `apply_event`; the
semantic dispatcher drops it, and the GPU is always semantic — so GPU
`Ctrl-V` does nothing today. Fix: route `Paste` **before the
grid/semantic split** (one handler for both attachment kinds) →
`paste_inbound` + `break_chain`.

That handler keys everything off the **dispatcher's authenticated
`source: FrontendId`** — `DispatcherEvent::FrontendEvent { source, .. }`
is stamped per attach session, while `Paste.frontend_id` is
client-supplied bytes. The current grid handler trusts the payload and
sets `active_frontend` from it, so a forged id pastes into another
frontend's active window (review blocker). The unified handler ignores
the payload id (logging a mismatch), targets `source`'s active view,
and calls `break_chain(source)`. A forged-id acceptance test pins it.

**(b) After-edit delivery — for the three scoped paths, not "every
command".** Three sites run edits outside `dispatch_key`'s revision
check and never fire `buffer.after-edit`: the minibuffer accept
callback (`M-x`), the menu invoke, and **paste**. Extract the
revision-compare-then-fire into a helper and call it at those three
sites. No double-fire on the keybound path.

Scope honesty (review correction): the helper keeps the existing
*active-buffer* before/after comparison, which is sound for these three
paths — kill, yank, menu Cut, and paste all edit the active buffer and
do not switch away mid-command. It is **not** a general guarantee: a
command that edits buffer A and then switches to B still evades the
compare (the check would diff B's revision). The general fix is a
buffer-aware edit epoch (any-buffer mutation counter + per-buffer hook
targeting) — deferred, named, and out of this PR's scope.

### Q#KR11 — Frontend lifecycle cleanup

`SessionDetached` already prunes six per-frontend maps
(`daemon.rs:1574`); `command_history` joins them. For the Lua side, the
same arm fires a new **`frontend.detached`** hook carrying the raw
frontend id; `killring.lua` subscribes and drops that frontend's
session/`last_kill_id` entries. (Frontend ids are monotonic, so without
this both maps grow for the daemon's lifetime — review note.) The hook
is tiny and generally useful (the first frontend-lifecycle hook).

## Phasing

One PR. In-diff order: Rust substrate (command boundaries + all eight
table rows, `clipboard_get/set`, unified paste route, after-edit helper
+ three call sites, `frontend.detached` + detach cleanup, module load)
→ `killring.lua` + `default.lua` bodies → acceptance.

## Bets (score at close)

1. **The eight-row boundary table is complete** — no further input path
   can edit a buffer or move point without rotating or breaking.
   (Falsified twice at smaller sizes; this is the bet to watch.)
2. **Stable entry ids make shared-ring interleaving safe** — no
   append-corruption, no index-shift mis-yanks, eviction invalidates
   cleanly.
3. **The unified paste route regresses nothing on the grid path** while
   making GPU paste work at all.
4. **Q#KR10's helper closes the after-edit hole at all three sites**
   with no double-fire.

## Deferred (named)

Unchanged from rev 2: word kills (five bindings) pending
bytes-returning deleters; `C-SPC`/mark; clipboard watching; ring
browser; ring persistence; `C-u C-y` / `C-M-w`. Plus: a Lua-visible
intercept probe (would upgrade Q#KR7's post-hoc accept to a preflight),
and a **buffer-aware edit epoch** so after-edit delivery covers
commands that edit one buffer then switch to another (Q#KR10b's named
general fix).

## Acceptance (dispatch_key-driven; multi-frontend via distinct `FrontendId`s)

Chain mechanics — rev 2 set, plus:
- **Pointer break, kill side**: `C-k`, click elsewhere in the same
  buffer (grid mouse path *and* semantic pointer path), `C-k` → two
  entries.
- **Pointer break, yank side**: `C-y`, click elsewhere, `M-y` →
  refused (not a yank), buffer unchanged at both locations.
- Wheel-scroll does **not** break a kill chain.

Shared-ring interleaving:
- **A-kill / B-kill / A-kill** → three entries; B's text intact
  (the `last_kill_id` blocker case).
- **A `C-y` / B kills / A `M-y`** → A rotates from its own entry
  (stable id), not from B's shifted position.
- Eviction mid-session (B pushes past the cap until A's entry drops) →
  A's `M-y` refuses cleanly.

Paste (Q#KR10a):
- `Paste` reaches the buffer on the **semantic** path (the GPU case —
  asserting the shipped bug is fixed), breaks the chain, and fires
  `buffer.after-edit` exactly once; grid path unchanged.
- **Forged-id paste**: frontend A sends `Paste` whose payload
  `frontend_id` names B → the text lands in **A's** active view, A's
  chain breaks, and B's state (view, chain, sessions) is untouched.

Hook delivery (Q#KR10b):
- `after-edit` probe fires exactly once for menu Cut, `M-x
  edit.kill-line`, and a paste; no double-fire for keybound `C-k`.

Lifecycle (Q#KR11):
- `SessionDetached` clears the frontend's `command_history` entry and
  fires `frontend.detached`; the killring module's tables for that id
  are gone (probe via `pmacs.killring._debug_sessions()` or list
  introspection).

Everything else carries over from rev 2: `M-x` three-direction matrix,
failed-kill/failed-yank no-ops, GPU-optimistic and unbound-key breaks,
slot sync + external-content integration, yank-over-selection, cap
validation (`math.huge`/`NaN`) and shrink-trim.