Merge pull request #150 from levineuwirth/docs-folding-stage2-landed

docs: record folding Stage 2 (#149) landing; open the Stage 3 lane

docs/active-work.md

@@ -14,9 +14,9 @@ backlog.
   machine-local: `origin` may name this canonical URL, a release mirror,
   or something else, and therefore has no authority by name alone.
 - Canonical base at this snapshot:
-  `githubsucks/main` @ `47581f4` (web grammars HTML+CSS #146 atop the LaTeX
+  `githubsucks/main` @ `6ed4fe9` (folding Stage 2 #149 atop the ledger
-  Stage 1 #144 / inline-math framing #145 pair and folding Stage 1 #142;
+  refresh #147, web grammars HTML+CSS #146, and the LaTeX Stage 1 #144 /
-  protocol v19).
+  inline-math framing #145 pair; protocol v19).
 - On the transfer source, `origin/main` named a release mirror at
   `d3fa632` and lagged badly. On the current destination, `origin` names
   the canonical URL. This difference is why all recovery begins by
@@ -50,55 +50,28 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `47581f4` or a newer intentional main.
+The first command must expose `6ed4fe9` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Folding Stage 2 lane (Arc 6) — IMPLEMENTED, PR #149 OPEN
+## Folding lane (Arc 6) — Stages 1 and 2 MERGED; Stage 3 (GPU) is next
 
-Stage 1 (the headless fold engine) is MERGED as **#142** (see "Closed since
+Both shipped stages are on `main`; nothing in this arc is in flight. Stage 3
-the last snapshot"); this lane carries the Stage 2 (grid/daemon collapse)
+has **no branch and no framing yet**.
-work off the resulting main.
 
-- Portable branch: `githubsucks/folding-tui`; worktree `../pmacs-folding-tui`.
+- Stage 1 (headless fold engine) merged as **#142**, Stage 2 (grid/daemon
-- Base: originally canonical `main` @ `c49a8c7`; `main` moved to `47581f4`
+  collapse) as **#149** — both under "Closed since the last snapshot".
-  (#146) during the arc, so the branch carries a **merge** of it. The merge
+- Retained, carrying nothing unmerged: branches `folding` / `folding-tui`
-  is textually clean but was NOT semantically clean — #146 added three new
+  and worktrees `../pmacs-folding` / `../pmacs-folding-tui`. The framings
-  `Viewport` literals to `src/highlight.rs`'s unit tests and Stage 2 gives
+  `docs/folding-framing.md` (rev 5) and `docs/folding-stage2-framing.md`
-  `Viewport` a `folds` field — so the carry-over is resolved in the merge
+  (rev 4) are the approved artifacts Stage 3 re-scouts against.
-  commit. Merged rather than rebased so the four framing revisions the
+- **Stage 3 (GPU) obligations, already named by the framings** — the
-  review rounds cite by SHA stay reachable.
+  starting point for its own framing doc: GPU collapse at TUI parity;
-- Framing head: `docs/folding-stage2-framing.md` **rev 4, APPROVED**
+  caret/hit-test fold-awareness; the `BufferSnapshot` **fold-mirror clear**
-  (`4222ffa`; rev 1 → 4 absorb review rounds 1–3). Numbering continues the
+  (parent R2-4 — without it, empty-after-revert diff suppression leaves
-  parent `Q#FD` scheme from `Q#FD12`.
+  stale folds on the GPU, the same trap class as #120); CRDT-origin and
-- State: **implemented; PR #149 OPEN, five review rounds so far, awaiting
+  GPU-optimistic interactive unfold (parent R2-3); and flipping
-  the merge word.** The spine (Q#FD12) is `src/fold_view.rs`'s
+  `FrontendView.fold_projection` to `true` for semantic frontends, which
-  `VisibleLineMap`, derived per rendered window and per command/event
+  Stage 2 deliberately left `false` (Q#FD21).
-  operation and never stored; fold projection is per-frontend
-  (`FrontendView.fold_projection`, Q#FD21). 48 acceptance tests in
-  `tests/folding_stage2_acceptance.rs`, each asserting on the real
-  `paint_frame` cell grid; every behavioral claim bite-verified. No wire
-  schema or protocol change — `FoldState` production (Stage 1) is
-  untouched; the GPU render path is Stage 3.
-- Review findings that changed the design, worth carrying forward: fold
-  projection must be per-frontend or a simultaneous unfolded GPU session's
-  cursor skips lines it displays (round 2); maps are per-window, and a
-  command's map follows the operation's TARGET window, not the active one
-  (rounds 2–3); crossing folds need merged hidden components, not
-  "outermost containing fold" (round 3); hidden-cursor motion must project
-  the whole POSITION and `set_view_top` must clamp in the setter (round 4);
-  the Lua widening must key on the **post-intercept** edit site, since a
-  managed intercept may relocate the op (round 5).
-- Next: remaining review rounds → merge word. Stage 3 (GPU) is a separate
-  branch/PR off the resulting main, re-framed in detail after Stage 2 lands.
-
-Recovery worktree:
-
-```sh
-git worktree add --track \
-  -b folding-tui \
-  ../pmacs-folding-tui \
-  githubsucks/folding-tui
-```
 
 ## Parked lane: kill-ring browser + persistence
 
@@ -136,6 +109,41 @@ git worktree add --track \
 
 ## Closed since the last snapshot
 
+- **Folding Stage 2 (grid/daemon collapse) — MERGED as #149** (`main` @
+  `6ed4fe9`, 2026-07-24, after **five** review rounds). The grid TUI now
+  renders collapses. Spine (Q#FD12): `src/fold_view.rs`'s `VisibleLineMap`,
+  derived from the fold store plus a window's line offsets and **never
+  stored**, threaded as `Option<&'a VisibleLineMap>` on a lifetime-bearing
+  `Viewport<'a>` that stays `Copy`. No wire schema or protocol change; the
+  GPU path is Stage 3. 48 acceptance tests on the real `paint_frame` grid,
+  every behavioral claim bite-verified. Durable design points, each a trap
+  Stage 3 inherits:
+  - the map's unit is a **merged hidden component** (overlapping *or
+    adjacent* intervals unioned, keeping the earliest visible head), not a
+    fold — folds may cross, and a later fold's own head can be hidden;
+  - instances are **per rendered window** and **per command/event
+    operation**, never per frame; a command's map follows the operation's
+    **target** window, since a wheel event names a pane without activating it;
+  - fold projection is **per-frontend** (`FrontendView.fold_projection`) —
+    shared `EditorCore` motion would otherwise make a simultaneous unfolded
+    GPU session's cursor skip lines it still displays;
+  - a hidden cursor normalizes by **position**, not row, and `set_view_top`
+    clamps in the setter rather than being repaired at render time;
+  - the interactive-Lua unfold keys on the **post-intercept** edit site — a
+    managed buffer intercept may legally relocate the op.
+
+  Process notes worth keeping: `main` moved under the arc, and the merge was
+  textually clean but **not semantically clean** (#146 added `Viewport`
+  literals the new `folds` field invalidated) — a clean `git merge-tree` does
+  not mean the merged tree compiles. CI was red at review on the macOS/luajit
+  `outline_5_level_100_entry_renders_within_100ms` budget flake and went
+  green on rerun.
+
+- **Documentation ledger refresh — MERGED as #147** (`main` @ `0a479ae`,
+  2026-07-24). The #142 housekeeping, expanded after review found the ledger
+  stale through four merges rather than one. Its own macOS/luajit red was the
+  vterm `VTERM_ALT_READY` PTY timeout; green on rerun.
+
 - **Web grammars HTML + CSS — MERGED as #146** (`main` @ `47581f4`,
   2026-07-23). `.html/.htm/.xhtml` and `.css` highlight off the official
   `tree-sitter-html` 0.23 / `tree-sitter-css` 0.25 crate query constants (no
@@ -164,9 +172,8 @@ git worktree add --track \
   carry nothing unmerged; the `folding-framing.md` framing is preserved.
   CI red at merge was an unrelated environmental perf flake
   (`outline_5_level_100_entry_renders_within_100ms`, macOS/luajit only),
-  green on rerun. Stage 2 is implemented and open as **PR #149** on
+  green on rerun. Stage 2 has since merged as **#149** (above); durable
-  `folding-tui` (see the lane above); durable substrate seams live in
+  substrate seams live in `docs/agent-handoff.md` §1.
-  `docs/agent-handoff.md` §1.
 
 - **Vterm Stage 3 (protocol v19 + GPU terminal) — MERGED as #135** (`main`
   @ `cac4961`, 2026-07-22, after two review rounds). Arc 5's terminal stage

docs/agent-handoff.md

@@ -1,7 +1,8 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-23, after web grammars HTML+CSS (#146) landed,
+**Last updated: 2026-07-24, after folding Stage 2 (#149, the grid/daemon
-following the LaTeX Stage 1 / inline-math framing pair (#144/#145), folding
+collapse) landed with its ledger refresh (#147), following web grammars HTML+CSS
+(#146), the LaTeX Stage 1 / inline-math framing pair (#144/#145), folding
 Stage 1 (#142, the headless fold engine), one-command GPU invocation (#141), the
 documentation refresh (#140), Vterm Stage 3 (#135, protocol v19 and native GPU terminal),
 tab-width rendering parity (#137), locals-query processing (#134), modeline
@@ -18,12 +19,13 @@ reads it the way you just did.
 For volatile branches, checkpoints, verification, and recovery
 commands, read `docs/active-work.md` immediately after this file.
 
-## 1. Where the project stands (2026-07-23)
+## 1. Where the project stands (2026-07-24)
 
-- `main` @ `47581f4` (web grammars HTML+CSS #146 atop LaTeX Stage 1 #144 /
+- `main` @ `6ed4fe9` (folding Stage 2 #149 + ledger refresh #147 atop web
-  inline-math framing #145 and folding Stage 1 #142), protocol **v19**
+  grammars #146, LaTeX Stage 1 #144 / inline-math framing #145, and folding
-  (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 = `FontFacts`, v18 =
+  Stage 1 #142), protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`,
-  `StatuslineSegments`, v19 = terminal frames/events).
+  v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal
+  frames/events).
 - **Folding Stage 1 (headless fold engine) LANDED — #142**
   (`docs/folding-framing.md` rev 5; merge `c49a8c7`; three review rounds,
   round 3 clean). Arc 6's engine — instance-side and headless; **no frontend
@@ -58,8 +60,8 @@ commands, read `docs/active-work.md` immediately after this file.
   - Durable lesson (round 2): after wiring a cleanup into a production hook,
     PIN IT THROUGH THE REAL PATH — a direct-call unit test misses the wiring
     (falsify by revert).
-  - **Stage 2 (grid/daemon collapse) is IMPLEMENTED — PR #149 OPEN** on
+  - **Stage 2 (grid/daemon collapse) LANDED — #149** (merge `6ed4fe9`; five
-    `folding-tui` (`docs/folding-stage2-framing.md` rev 4, approved). Its
+    review rounds; `docs/folding-stage2-framing.md` rev 4). Its
     load-bearing reframe: the TUI had **no non-identity
     source-line↔display-row map** (`view_top + row` was baked into ~13 sites),
     so Stage 2's spine is `src/fold_view.rs`'s `VisibleLineMap` — derived from
@@ -83,7 +85,12 @@ commands, read `docs/active-work.md` immediately after this file.
       clamps in the setter rather than being repaired at render time;
     - the interactive-Lua unfold keys on the **post-intercept** edit site — a
       managed buffer intercept may legally relocate the op.
-    No protocol bump. Stage 3 (GPU) follows.
+    No protocol bump. **Stage 3 (GPU) is next and has no framing yet**; its
+    named obligations are GPU collapse at TUI parity, caret/hit-test
+    fold-awareness, the `BufferSnapshot` **fold-mirror clear** (parent R2-4 —
+    the #120 trap class), CRDT-origin / GPU-optimistic interactive unfold
+    (parent R2-3), and flipping `FrontendView.fold_projection` to `true` for
+    semantic frontends.
 - **One-command GPU invocation LANDED — #141**
   (`docs/gpu-invocation-framing.md` rev 6; merge `63fbc66`; two implementation
   reviews). The additive public path is `pmacs --gpu [--socket NAME|PATH]`;
@@ -483,13 +490,15 @@ commands, read `docs/active-work.md` immediately after this file.
     lexical resolution, settled per-layer facts, shared TUI/GPU
     local-predicate filtering, and a registry-wide locals-query invariant
     shipped without a protocol change.
-  - **Arc 6 (folding) Stage 1 LANDED — #142** — the headless fold engine
+  - **Arc 6 (folding) Stages 1 and 2 LANDED — #142 and #149** — the headless
-    (store, structural source, Lua `C-c @` surface, command-path unfold,
+    fold engine (store, structural source, Lua `C-c @` surface, command-path
-    `FoldState` production). Stage 2 (grid/daemon collapse) is implemented and
+    unfold, `FoldState` production), then the grid/daemon collapse (the
-    open as **PR #149** on `folding-tui`; Stage 3 (GPU) follows.
+    `VisibleLineMap` spine, fold-aware gutter/diagnostics/caret/selection/
+    presence/viewport/motion, and the interactive unfold widening). **Stage 3
+    (GPU) is next**, unframed.
   - **Web grammars HTML+CSS LANDED — #146**, and **LaTeX Stage 1 — #144**
     with its inline-math parent framing **#145**.
-  - Remaining ranked arcs: 6 folding Stages 2–3, 7 DAP, 8 GPU splits, plus
+  - Remaining ranked arcs: 6 folding Stage 3, 7 DAP, 8 GPU splits, plus
     the `.ipynb` arc (its JSON-grammar prerequisite shipped in #123).
 
 ## 2. How we work (the part that must not drift)