pmacs/docs/folding-framing.md

# Folding — framing (Arc 6)

**Revision 5 — 2026-07-23. Status: APPROVED; Stage 1 implementing on branch
`folding` (rebased onto canonical `main` @ `96d0bae`).** Rev 1 passed a
ground-truth review; rev 2 fixed round 1's seven findings; rev 3 fixed round
2's five majors and four minors; rev 4 fixes round 3's one major, three
minors, and a nit; rev 5 records the settled keybinding decision (Q#FD4) and
approval. See §0 for the per-round changelog.

## 0. Revision history

### Round 1 (rev 1 → rev 2)

- **F1** the grid TUI is daemon-rendered and never receives `FoldState`; its
  collapse is instance-side in the daemon grid renderer. Staging reworked.
- **F2** stored range pinned to a line-aligned interior.
- **F3** the store's translation is the instance-side buffer-attached `View`
  (`BufferStyleSpanTranslator` pattern), not the frontend `translate_byte_range`.
- **F4** stale-tree fold creation refuses.
- **F5** multi-frontend point / edit-vs-fold pinned.
- **F6** explicit-buffer Lua API + validation.
- **F7** authoritative-empty `FoldState`.

### Round 2 (rev 2 → rev 3)

- **R2-1 (major).** The block-kind heuristic picked a **body line** as the
  fold head on indentation grammars — tree-sitter-python's `block` starts on
  the first statement line, so `def foo():` was left above a headless fold
  (verified in review; brace languages escaped only because `{` shares the
  introducer line). Fixed with a **head-selection ascend rule** (Q#FD1, §3),
  a no-op for brace languages. Acceptance 1 now tests both languages.
- **R2-2 (major).** The interactive-vs-programmatic split cannot live in the
  store's `View`: `View::on_edit(&Buffer, &Edit)` (`src/overlay.rs:248`) and
  `Edit` (`src/rope.rs`) carry no source frontend and no "point was inside"
  signal — only optional `crdt_op`. The `View` does **translate + drop only**;
  the **unfold is a pre-edit step at the dispatch/command layer** that knows
  the authenticated frontend and its point (Q#FD5, §5). This is the
  handoff's deferred "origin-pinned `buffer.after-edit` fan-out" gap.
- **R2-3 (major).** "CRDT op = remote = translate" misclassifies GPU typing
  (a GPU user types via CRDT ops but is editing at their own point inside a
  rendered fold). The classifier is the **authenticated source frontend's
  point, not the transport**. Stage 1 implements the unfold for the command
  path; **CRDT-origin unfold is a named Stage 3 obligation** (that is when a
  GPU user can type into a rendered fold). Q#FD5, §5, §8.
- **R2-4 (major).** Q#FD8 recreated the #120 stale-mirror trap: revert drops
  the store, emits `BufferSnapshot`, and resets the producer baseline, so the
  now-empty store is suppressed as "initial empty" and a GPU keeps rendering
  pre-revert folds unless its snapshot arm **clears the fold mirror**. That
  frontend clear is load-bearing; named as a Stage 3 obligation and pinned in
  acceptance 7 (Q#FD8, §5). Same class as [[message-gating-on-active-state]].
- **R2-5 (major).** A line-aligned tail hid non-member text on shared-closer
  lines (`} else {`, `}, [deps])`). Fixed by **keeping a closing-delimiter
  line visible** (Q#FD3, §5); delimiter-less (indentation) nodes still hide
  through their last body line. Decided, not bet.
- **Minors.** (a) unfold is **plural** — every fold containing the point.
  (b) a shared head line (`foo(() => {`) toggles **innermost-first**.
  (c) Q#FD9's rejection reason corrected: `(0,0)` is in-bounds; the reject
  comes from the ≥1-hidden-line rule. (d) Stage 2/3 re-framings must address
  three named interactions (§8): fold-aware `LineNumbers`, visible-line
  viewport/scroll accounting, and hidden-line signs/presence clamp-or-drop.

### Round 3 (rev 3 → rev 4)

- **R3-1 (major).** Rev 3's head-selection ascend was **not** a no-op for
  brace languages: rustfmt wraps long signatures (`fn foo(` / `a: u32,` /
  `) -> bool {`) and puts `{` on its own line under a `where` clause, so
  `block.start_line > parent.start_line`, the ascend fired, and the fold hid
  the wrapped signature — the R2-5 defect class reintroduced one level up.
  Replaced by a **derived head line**: the interior comes from the body node
  alone (closer-aware tail unchanged) and the head is **the line immediately
  above the first hidden line** (§3) — Emacs hideshow / LSP `foldingRange`
  parity; wrapped introducer text now stays visible in both grammar shapes.
  The introducer↔body association survives for **matching and `close-all`
  only**. Acceptance 1 gains wrapped-signature cases.
- **R3-2 (minor).** "Innermost-first" on a shared head line made the outer
  fold unreachable via `fold.toggle` (close inner, reopen inner, forever)
  and allowed zero-visible-change presses. Replaced by **state-aware
  ordering** with an org-TAB-style toggle cycle (§6); acceptance 9 updated.
- **R3-3 (minor).** Stage 1's "command path" is `dispatch_key`
  self-insert/delete only; interactive Lua commands (yank, query-replace,
  comment-toggle) mutate through the Lua mutator path and classify
  programmatic, so their edits land inside a fold without unfolding. Now
  stated as the intended Stage 1 line, and **widening the classifier to
  interactive Lua command contexts is a named Stage 2 obligation** (Q#FD5,
  §5, §8), beside Stage 3's CRDT-origin unfold.
- **R3-4 (minor).** The data API's normalization of an arbitrary range was
  unstated; §6 now defines it (no node, so no introducer or closer
  inference). **Nit:** stored-range containment pinned **start-exclusive,
  end-inclusive** with the matching `View` boundary bias, so typing at the
  end of a head line neither unfolds nor lands hidden (§5; acceptance 6).

### Approval + keybindings (rev 4 → rev 5)

- **Q#FD4 keybindings decided.** rev 4 deferred the binding to the user; the
  user chose **Emacs hideshow parity**, so Stage 1 ships the `C-c @` prefix
  set (§6, §9) — `C-c <letter>` is fully taken by the LSP surface, and the
  `C-c @` hs-minor-mode prefix collides with nothing. This follows the
  M-;/M-% precedent of shipping faithful Emacs-idiom defaults.
- **Bet B1 accepted as framed** (block-kind target heuristic; curated Tier-1
  queries the named fallback). rev 4's architecture is **approved**; Stage 1
  implements on this branch, rebased onto canonical `main` @ `96d0bae`.

## 1. Problem and what ships

Pmacs cannot fold. `FoldState` was declared in the M11.1 semantic-frontend
design but has never been produced — the producer says "pmacs has no
instance-side fold source yet," and a test pins it is never emitted.

Arc 6 gives pmacs a fold engine (instance-side fold store + a fold source +
Lua commands), renders collapsed regions with a gutter fold marker in both
frontends, and produces `FoldState` for semantic (GPU) sessions. It is the
roadmap's "keystone gutter rider."

**`FoldState` needs no protocol bump** — the variant has been in the encoding
since M11.1 and both frontends already decode it (the TUI drops it, the GPU
has a decode arm); Arc 6 only starts *producing* it.

**Git gutter markers are a SIBLING rider, not this arc** (§11).

## 2. Ground truth (scouted 2026-07-22, `main` @ `cac4961`; verified across three review rounds)

- **`FoldState { buffer_id, folds: Vec<ByteRange> }`** —
  `pmacs-protocol/src/message.rs:886`, gated on `semantic_render`,
  DECLARED-BUT-UNPRODUCED. `semantic_render.rs:4002` pins it is never emitted.
- **`BlockAdornments`** (also unproduced) is the declared home for
  folded-region placeholders. Arc 6 does not produce it (Q#FD7).
- **No fold source exists** — the bundled grammars export
  `HIGHLIGHTS`/`INJECTIONS`/`LOCALS`/`TAGS` only, no fold query, no
  `folds.scm`. Fold source is Q#FD1. **tree-sitter-python's `block` node
  starts on the first statement line, not the `def` line** (R2-1), and
  **tree-sitter-rust's `block` starts at `{`, which rustfmt places below the
  `fn` line for wrapped signatures and standalone under `where` clauses**
  (R3-1) — the two facts the derived-head rule answers.
- **Two frontend render paths (F1).** Grid TUI: daemon-rendered
  (`render_states` → `render_state.render_frame`, `src/daemon.rs:1106`),
  advertises `semantic_render: false` (`src/frontend.rs:385`), never receives
  `FoldState`. GPU: semantic session (`semantic_states` → `sem.render_frame`,
  `:1091`), does. Collapse is daemon-side for the TUI, wire-fed for the GPU.
- **Gutter signs are frontend-derived, not a wire channel** — fold markers
  follow suit per path; no new wire type.
- **Instance-side edit translation** is the buffer-attached `View`
  (`BufferStyleSpanTranslator`, `src/overlay.rs:235`; hook
  `on_edit(&Buffer, &Edit)` at `:248`), which sees every edit once,
  provenance-blind (R2-2): `Edit` carries only `crdt_op`, no source frontend.
- **Staleness is detectable** — `ParseViewHandle::current()`
  (`src/syntax.rs:696`) is `None` before first settle; `pending_edit_count()`
  (`:706`) is nonzero while edits await settle.
- **Greenfield** Lua/commands.

## 3. Fold source (Q#FD1) — structural node folding with derived head line and closer-aware tail

The grammars ship no fold queries, so pmacs defines "what is foldable." v1 is
**structural node folding for grammar-backed buffers** (reuses the parse trees
for every bundled grammar and injection layer, zero per-language authoring).
Indentation folding (grammarless fallback) and curated per-language queries
(quality pass) are DEFERRED (§11).

The source, at a point:

1. **Match** the nearest enclosing NAMED node spanning **≥2 source lines**
   (source lines, not display rows — soft wrap is frontend-only and unknowable
   instance-side), biased to block-like kinds (`block`, `body`, `*_list`,
   `declaration_list`, `statement_block`, brace/bracket-delimited nodes).
2. **Resolve introducer↔body (R2-1, R3-1).** If the matched node is an
   introducer — a `function_definition` / `if_statement` / … matched from its
   header lines, whose block-like body child (grammar field `body` /
   `consequence`; feeds B1) starts at or below it — descend to that body
   child. The interior-defining node `B` is the body; otherwise it is the
   matched node itself. `B` is *introduced* when its parent is such an
   introducer. The association exists for **matching and `close-all`
   enumeration only** — `fold.toggle` on `def foo():` or on any
   wrapped-signature line resolves to the body below; it no longer selects
   the head line (rev 3's start-line ascend is removed, R3-1).
3. **Head — the line immediately above the first hidden line (R3-1).** The
   head line is `B.start_line - 1` when `B` is an **introduced,
   delimiter-less body** (a Python `block`: its introducer's header ends on
   the line above — `def foo():`, or the `):` line when the signature
   wraps). Otherwise it is `B.start_line` (a brace body's `{` line —
   normally the introducer's own line; the `) -> bool {` line when rustfmt
   wraps the signature; the standalone `{` under a `where` clause). The
   first hidden line is `head_line + 1`. **Wrapped introducer text always
   stays visible** — rev 3's ascend took the introducer's *start* line as
   the head and so hid wrapped signatures and `where` clauses, the R2-5
   defect class one level up. This is Emacs hideshow / LSP `foldingRange`
   parity: the fold hides the body, nothing else.
4. **Tail — closer-aware (R2-5).** The last hidden line is:
   - if `B`'s last line begins with `B`'s **closing-delimiter token**
     (`}`/`)`/`]`, and `end`-style closers later) — a brace/bracket node —
     then `B.last_line - 1`, **keeping the closer line visible**. This is what
     keeps `} else {` and `}, [deps])` on screen with their trailing siblings.
   - else (a delimiter-less node, e.g. a Python `block`) — `B.last_line`,
     hiding through the last body line.

The stored range is the byte range `[end of head_line, end of last-hidden
line]` (§5). A fold must have **≥1 hidden line**: the ≥2-source-line gate is
a *match* condition on the matched node, foldability is the ≥1-hidden-line
rule on the *normalized* interior. So `fn f() {` / `}` (empty body — the
closer-aware tail leaves nothing between head and closer) is **not
foldable**, while a two-line `def foo():` / `x = 1` **is**: the matched
`function_definition` spans two lines and its one-line body is the interior.

**Stale-tree rule (Q#FD10, F4).** The source reads
`ParseViewHandle::current()`; if it is `None` (no settle yet) or
`pending_edit_count() > 0` (settled coordinates are stale), the fold command
**refuses with a status message and stores nothing** — a fold is durable state
and must not be computed against stale coordinates. Settle is a main-thread
pump, so the window is sub-frame. Translate-through-pending is a §11
refinement.

The block-kind heuristic (step 1) and the body-field bias (step 2) remain a
taste bet (Bet B1); steps 3–4 fixed the *determinable* defects (R2-1, R2-5,
R3-1), which were not taste.

## 4. Where fold state lives (Q#FD2)

Instance-side, per the wire contract. A **per-buffer fold store** (a set of
byte ranges) lives beside the buffer, attached as a `View` (F3). Commands
mutate it; the daemon grid renderer reads it directly (Stage 2); the semantic
producer ships it as `FoldState` to GPU sessions (Stage 3). Nested folds are
allowed; the store is **shared by every attached frontend** (Emacs parity).

## 5. Fold model semantics (Q#FD3, Q#FD5, Q#FD6, Q#FD8)

**Stored range = line-aligned hidden interior (Q#FD3).** A fold is identified
by its **head line** (the line immediately above the hidden interior, §3
step 3), which stays visible with a frontend-drawn ellipsis. The stored byte
range is `[end of head line, end of the last hidden line]`, where the last
hidden line is chosen by §3 step 4 — so a **closing-delimiter line stays
visible** (fixing `} else {`), while a delimiter-less node hides through its
last body line. One normalized form is computed by the source and seen
identically by the store, the grid renderer, the wire, and `folds()`.

**Containment and boundary bias (R3-4 nit).** The stored range is
**start-exclusive, end-inclusive** — `(start, end]`. A point at
`range.start` (the end of the head line) is **outside** the fold: typing
there does not trigger the pre-edit unfold, and the store `View` translates
an insert at exactly `range.start` by shifting the fold right (the
`BufferStyleSpanTranslator` at-or-after bias), so the typed character lands
visible on the head line. A point at `range.end` (the end of the last hidden
line) is **inside**: typing there unfolds. One convention covers both the
containment test and the translation bias.

**Point and folds (Q#FD3, F5).**
- Folding a range containing the **invoking frontend's** point moves that
  point to the head line.
- The store is shared, so another frontend's cursor may sit inside a newly
  folded range. "No cursor inside a fold" is a **per-cursor, render-time**
  invariant (its caret clamps to the head on that frontend's next frame — a
  Stage 2/3 concern). In **Stage 1** there is no motion-awareness, so the
  invariant is **creation-time-only**; acceptance is scoped to that so it
  cannot self-contradict.

**Edits and folds — two separated mechanisms (Q#FD5, Q#FD6, R2-2, R2-3).**
- The store's buffer-attached `View` does **translation and drop only**, and
  is **provenance-blind**: on every edit it translates each fold's range, and
  **drops** any fold whose head/tail the edit destroys or whose interior
  collapses below one line. It cannot unfold-on-typing because `Edit` carries
  no frontend and no point (R2-2).
- **Unfolding on an interactive edit is a pre-edit step at the dispatch layer**
  (which holds the authenticated frontend and its point): before applying an
  edit that a frontend is making at its point, unfold **every** fold
  containing that point (plural — minor a). The classifier is the
  **authenticated source frontend's point, not the transport** (R2-3): a GPU
  user's CRDT-op insert at a point inside a fold is interactive and must
  unfold, even though it arrives as a CRDT op. **Stage 1 implements this for
  the command path** — daemon `dispatch_key` self-insert/delete, the only
  point-anchored edits the daemon applies directly with the frontend + point
  in hand. Two widenings are named, each landing with the rendering that
  makes it user-visible (R3-3):
  - **Interactive Lua command edits — Stage 2 obligation.** Yank,
    query-replace, and comment-toggle mutate through the Lua mutator path,
    which this split classifies as programmatic: in Stage 1 such an edit
    inside a fold translates without unfolding. Invisible while headless,
    but a visible "the yank vanished into the fold" once the TUI collapses —
    Stage 2 widens the classifier to interactive Lua command contexts,
    keyed on the edit position.
  - **CRDT-origin unfold — Stage 3 obligation**, wired when the GPU renders
    folds and a GPU user can type into one.

**Store lifecycle vs producer baseline (Q#FD8, F3, R2-4).** Three coupled
resets, kept distinct:
- The **per-session producer suppression baseline** resets on `BufferSnapshot`
  so the fold set is re-shipped to a (re)joining semantic session.
- The **per-buffer store** is dropped on buffer **content replacement**
  (revert/reload) — its ranges name bytes that no longer exist (revalidation
  is a §11 refinement).
- **The frontend fold mirror must clear on `BufferSnapshot` (R2-4, Stage 3
  obligation).** Revert simultaneously drops the store, emits a snapshot, and
  resets the baseline, so the producer sees an empty store with a fresh
  baseline and correctly suppresses it as "initial empty" — which means the
  GPU keeps rendering pre-revert folds **unless its snapshot arm clears fold
  state**, exactly as it already clears spans/decorations. The
  empty-after-snapshot suppression is correct **only because** the snapshot
  clears the frontend mirror; this pairing is load-bearing and is pinned in
  acceptance 7.

## 6. Lua command surface and validation (Q#FD4, Q#FD11)

**Interactive commands** (resolve to the invoking frontend's active-window
buffer — command context, not ambient resolution):

- `fold.toggle`, `fold.close`, `fold.open`, `fold.close-all`, `fold.open-all`.
- `close-all` folds **top-level** foldable regions only (Emacs `hs-hide-all`
  parity — nested regions are not auto-folded; feeds B2). `open-all` clears.
- **Shared head lines — state-aware ordering (R3-2).** On a head line shared
  by more than one fold (`foo(() => {`), plain "innermost-first" dead-loops:
  toggle closes the inner fold, then acts on it again and *reopens* it,
  forever — the outer fold is unreachable, and opening an inner fold while
  the outer is closed changes nothing on screen. Ordering is therefore
  keyed on fold **state** so every press has a visible effect: `fold.close`
  closes the **innermost open** fold (repeated presses walk outward);
  `fold.open` opens the **outermost closed** fold (repeated presses walk
  inward); `fold.toggle` **cycles org-TAB-style** — it closes the innermost
  open fold until every fold on the head is closed, then one more press
  opens them all.

**Data API (Q#FD4, F6): explicit buffer, no ambient resolution** (matching
#127): `pmacs.fold.fold(buffer, range)`, `unfold(buffer, range)`,
`folds(buffer)`, `toggle(buffer, pos)`.

**Arbitrary-range normalization (R3-4).** A data-API `fold(buffer, range)`
carries no node, so none of §3's introducer or closer inference applies —
the caller names exactly what to hide. The head line is the line containing
`range.start`; the hidden lines are the full lines strictly after it,
through the line containing `range.end` — or through the *previous* line
when `range.end` sits at a line start. The stored form is §5's; validation
then applies.

**Validation (Q#FD11, F6).** `fold(buffer, range)` rejects unless: the buffer
is a normal document buffer; both endpoints are UTF-8 boundaries; and the
range normalizes to **≥1 hidden line**. Q#FD9 (terminals never fold) follows
from the last clause (minor c): `(0,0)` on an empty terminal identity buffer
is technically in-bounds, but it normalizes to zero hidden lines and is
rejected — no special case.

**Default bindings (Q#FD4) — Emacs hideshow parity.** Stage 1 ships the
`C-c @` prefix set. `C-c <letter>` is fully taken by the LSP surface, so the
Emacs hs-minor-mode prefix `C-c @` is the one faithful choice that collides
with nothing:

- `C-c @ C-c` → `fold.toggle` (org-TAB-style cycle)
- `C-c @ C-h` → `fold.close`
- `C-c @ C-s` → `fold.open`
- `C-c @ C-M-h` → `fold.close-all`
- `C-c @ C-M-s` → `fold.open-all`

These follow the M-;/M-% precedent of shipping faithful Emacs-idiom
defaults; users rebind through `pmacs.keymap` as usual.

## 7. Frontend collapse + gutter marker (Q#FD7)

- **Grid TUI — daemon-rendered.** The daemon grid renderer reads the store and
  omits each fold's hidden lines, showing the head line with an ellipsis and a
  gutter fold glyph. No wire (the vterm Stage 2 shape).
- **Semantic GPU — wire-fed.** The GPU receives `FoldState`, excludes the
  hidden bytes from its shaped slice, shows the head + ellipsis + fold glyph,
  and makes caret/hit-test fold-aware. It also clears its fold mirror on
  `BufferSnapshot` (R2-4).

The placeholder is frontend-local (not a `BlockAdornment`); the gutter marker
is derived per path like the diagnostic sign bars — no new wire type.

## 8. Staging and scope

- **Stage 1 — fold engine (instance), headless.** The per-buffer store + its
  translating/dropping `View`; the structural source with derived head line,
  closer-aware tail, and the stale-tree rule; the Lua data API + interactive
  commands + validation; the **command-path pre-edit unfold**; `FoldState`
  production (authoritative-empty, diff-suppressed); headless acceptance. No
  rendering. **Approval-critical.**
- **Stage 2 — grid (daemon-rendered) collapse + gutter marker.** The daemon
  grid renderer collapses folded interiors and draws the TUI gutter glyph +
  head placeholder; caret clamps to the head. **Must also make the
  daemon-computed `LineNumbers` family fold-aware** (skipped lines; relative
  distance measured across a fold), **count visible lines in viewport/scroll
  accounting**, **clamp-to-head-or-drop diagnostic signs on hidden lines**
  (minor d), and **widen the pre-edit interactive unfold to interactive Lua
  command edits** (yank / query-replace / comment-toggle — R3-3).
- **Stage 3 — GPU collapse + gutter marker.** The GPU consumes `FoldState`,
  excludes folded bytes, draws the glyph, makes caret/hit-test fold-aware at
  TUI parity, **clears the fold mirror on `BufferSnapshot`** (R2-4), wires
  **CRDT-origin interactive unfold** (R2-3), and applies the same
  hidden-line rules to **peer-presence rects and line numbers** (minor d).

Stages 2–3 are sketched; each is re-framed in detail after the prior stage
lands. This framing asks approval for the architecture and Stage 1's detail.

## 9. Numbered decisions

- **Q#FD1** Structural node folding: match block-like node ≥2 source lines →
  resolve introducer↔body (matching + `close-all` only) → **head line = the
  line immediately above the first hidden line** (wrapped introducer text
  always visible) → **closer-aware tail** (closing-delimiter line kept
  visible; delimiter-less nodes hide through the last body line);
  stale/absent tree refuses. Indentation and curated queries deferred. (§3)
- **Q#FD2** Fold state is instance-side, per-buffer, a set of ranges, shared
  by all frontends; nested allowed. (§4)
- **Q#FD3** Stored range = line-aligned hidden interior, **start-exclusive,
  end-inclusive** with the matching `View` boundary bias; head line (the
  line above the interior) visible; closer line visible for closer-terminated
  nodes; invoking point moves to the head; no-cursor-inside is per-cursor
  render-time, creation-time-only in Stage 1. (§5)
- **Q#FD4** Interactive commands (invoking frontend's buffer; shared head
  lines use **state-aware ordering** — close innermost-open, open
  outermost-closed, toggle cycles); data API takes an explicit buffer, no
  ambient resolution, with the §6 arbitrary-range normalization; **default
  bindings = the Emacs hideshow `C-c @` prefix set** (§6), rebindable. (§6)
- **Q#FD5** The store `View` translates + drops only (provenance-blind); the
  **pre-edit interactive unfold** lives at the dispatch layer, keyed on the
  authenticated source frontend's point (not transport), unfolding **every**
  fold containing it; Stage 1 = command path (`dispatch_key`
  self-insert/delete), interactive-Lua-command widening = Stage 2,
  CRDT-origin = Stage 3. (§5)
- **Q#FD6** A fold whose head/tail an edit destroys is dropped, not
  re-anchored. (§5)
- **Q#FD7** Placeholder + gutter marker are frontend-local per path (TUI
  daemon-rendered, GPU wire-fed); `BlockAdornments` stays unproduced; no new
  wire type. (§7)
- **Q#FD8** `FoldState` (semantic sessions only) is whole-buffer,
  authoritative-empty (initial empty suppressed until a fold exists; unchanged
  suppressed; non-empty→empty emits exactly one empty frame); its per-session
  baseline resets on `BufferSnapshot`; the STORE drops on content replacement;
  **the GPU fold mirror must clear on `BufferSnapshot`** or empty-after-revert
  suppression leaves stale folds (#120 class). (§5, §8)
- **Q#FD9** Terminals never fold — from the ≥1-hidden-line validation, not
  from bounds. (§6)
- **Q#FD10** Fold creation against a `None`/stale parse tree refuses. (§3)
- **Q#FD11** `fold(buffer, range)` validates buffer kind, UTF-8 boundaries,
  and ≥1 hidden line after the §6 normalization; rejects otherwise. (§6)

## 10. Bets

- **B1** The block-kind heuristic (§3 step 1) and body-field bias (step 2)
  pick a fold *target* users find natural. FALSIFIABLE on real Rust/Python;
  fallback is curated Tier-1 queries. (The derived head line and the
  closer-aware tail are decided, not bet.)
- **B2** Whole-buffer `FoldState` is cheap: folds are a handful, `close-all`
  is top-level only, so the set is O(top-level blocks). No viewport scoping.
- **B3** Both collapse paths reuse existing machinery (daemon cell painting;
  the GPU's projected↔source map) — no new layout engine.

## 11. Deferred (named)

- Indentation folding for grammarless buffers (Q#FD1 (C)).
- Curated per-language fold queries (Q#FD1 (A)).
- Translate-a-node-range-through-pending-edits so creation need not refuse on a
  stale tree (Q#FD10 refinement).
- Fold-store revalidation against new content on revert/reload (v1 drops it).
- Persisted folds across sessions; `fold.hide-level N`; auto-fold-on-open.
- `BlockAdornments` production (rich placeholders, diff zones, blame bands).
- **Git gutter markers** — the sibling gutter rider; separate diff source.
- Search revealing folds (a match inside a fold auto-unfolds) — Stage 2+.

## 12. Acceptance — Stage 1 (engine)

1. **Head line, both grammar shapes, wrapped headers (R2-1, R3-1).** In Rust
   `fn foo() { … }`, a point in the body folds with head line `fn foo() {`;
   with a rustfmt-wrapped signature (`fn foo(` / `a: u32,` / `) -> bool {`)
   the head is the `) -> bool {` line and **every signature line stays
   visible**. In Python `def foo(): / body`, a point in the body folds with
   head line `def foo():` — **not** a body line; with a wrapped signature
   the head is the `):` line and the signature stays visible. `close-all`
   on each yields the same heads.
2. **Stale/absent tree (Q#FD10).** With `current() == None`, and with
   `pending_edit_count() > 0` after an edit before settle, `fold.toggle`
   refuses and stores nothing; after settle it succeeds.
3. **Commands.** `fold.toggle` folds the enclosing region and unfolds on a
   head; `close-all` folds top-level regions only (a nested inner region is
   not auto-folded); `open-all` clears.
4. **Range semantics (Q#FD3, R2-5).** For a brace node the closing-delimiter
   line is **outside** the stored range (stays visible) and a `} else {` case
   keeps `else {` visible; for a Python node the last body line is **inside**
   the range (hidden). `folds(buffer)` returns exactly the normalized ranges.
5. **Point (Q#FD3).** Folding a range containing the invoking point moves it
   to the head; Stage 1 does not prevent later motion into a fold.
6. **Edits — separated mechanisms (Q#FD5/Q#FD6, R2-2/3, R3-3/4).** The store
   `View` translates a fold across a programmatic edit inside it and drops a
   fold whose head an edit deletes — with no knowledge of source. A
   command-path self-insert at a point inside a fold (or inside **nested**
   folds) unfolds **all** of them before the edit applies. A self-insert at
   the **end of the head line** (`point == range.start`) unfolds **nothing**
   and the fold shifts right — the character lands visible on the head line.
   An interactive Lua-command edit (e.g. a yank) inside a fold translates
   without unfolding in Stage 1; the test documents this as the named
   Stage 2 widening. (CRDT-origin unfold is asserted in Stage 3.)
7. **`FoldState` production (Q#FD8, F7, R2-4).** The flipped pin test asserts
   all three transitions to a semantic session — nothing until a fold exists,
   nothing when unchanged, exactly one empty frame after `open-all` — while
   `BlockAdornments` is still never emitted; the per-session baseline resets on
   `BufferSnapshot`. The test documents that empty-after-snapshot suppression
   is correct only paired with the Stage 3 frontend-mirror clear.
8. **Store lifecycle.** Buffer content replacement (revert) drops the store.
9. **Nested folds (R3-2).** Folding an inner then an outer region yields two
   ranges; `open-all` clears both. On a shared head line: repeated
   `fold.close` closes innermost-then-outer, repeated `fold.open` opens
   outermost-then-inner, and `fold.toggle` cycles close-inner → close-outer
   → open-all — the outer fold is reachable by every command.
10. **Injected layer.** A fold sourced inside an injected layer — a fenced
    code block in a markdown buffer — returns the inner block's range, proving
    the source walks injection layers, not just the root tree.
11. **Lua data API (Q#FD4/Q#FD11, R3-4).** `pmacs.fold.*` with an explicit
    buffer drives the above and round-trips `folds()`; an out-of-bounds,
    non-boundary, or sub-one-line range is rejected — including a range
    whose `end` sits at the start of the line after its head, which
    normalizes to zero hidden lines; a fold on a terminal identity buffer
    is rejected via the ≥1-hidden-line rule (Q#FD9).

## 13. Gates (Stage 1)

`cargo fmt --check`; strict workspace Clippy; `cargo test --lib` and
`--features crdt`; `tests/folding_acceptance.rs` (default + CRDT); `cargo test
--test m4_acceptance -- --skip basedpyright`; `PMACS_REQUIRE_GPU=1 cargo test
-p pmacs-gpu`; the workspace sweep; `git diff --check`. New behavioral
acceptance is bite-verified with `scripts/bite`.

## 14. Branch and PR plan

Branch `folding`, worktree `../pmacs-folding`. This framing (rev 1 → rev 5)
is its opening commits; the branch was **rebased onto canonical `main` @
`96d0bae`** when implementation started (the earlier base `cac4961` was
behind after the documentation + tab-width #137 housekeeping; Stage 1's
instance-side scope does not overlap that work). Stage 1 implements on this
same branch and opens as the first folding PR. Stages 2 and 3 are separate
branches/PRs off the main resulting from the prior stage, each with its own
detailed framing.