neuwirth
/
pmacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: frame bottom-panel Stage 3 — the adopter default flip 

Arc 7's last step. Stages 1, 2A, 2B-1, 2B-2 and 2B-3 are all on main;
the panel is complete on both frontends and every mechanism this stage
needs exists. What remains is the decision the arc deferred on purpose:
omitting `display` should mean the panel, not the selected window.

Revision 2, approved with amendments. The scout found the parent
framing's plan sound and two of its details drifted.

THE FLIP IS THREE SITES IN TWO LANGUAGES, and a fourth validator that
must not move. `parse_adopter_placement` reads like the shared parser
its doc comment implies but has EXACTLY ONE CALLER, the terminal;
listview and compile each re-implement the same three-value validation
in Lua, including their own copy of the error message. Changing only
the Rust parser would leave both Lua adopters resolving omission to the
current window — a half-flip that looks done and behaves inconsistently
per adopter.

DIRED IS A FOURTH COPY OF THE VALIDATOR AND MUST KEEP `"current"`.
Review caught this; revision 1 had it as a leaning. The mechanism is
specific rather than stylistic: `pmacs.path.set_directory_handler`
passes `{ dest = dest }` with NO `display` key, so `pmacs .` resolves
by omission. Flipping dired's default would open the golden journey's
first directory listing in a bottom panel. The distinction that makes
this principled rather than an exception: listview, compile and terminal
produce output the user CONSULTS; dired produces a document the user
WORKS IN. The panel default is right for the first kind and wrong for
the second.

UNIFY NARROWLY, NOT WHOLESALE. A shared
`resolve_adopter_display(operation, raw, default)` owns the vocabulary,
the error text and the default policy, with dired passing
`default = "current"` so its exemption is a parameter rather than a
divergent copy. Terminal's `window` mutual-exclusion stays in its Rust
wrapper — the parsers are not identical and a helper pretending
otherwise would be its own defect.

One normalization is named rather than absorbed: terminal reads
`get::<Option<String>>("display")?`, so a non-string value raises mlua's
TYPE error before the custom "unknown display" message, while the Lua
callers `tostring()` it into their own. Different observable behaviour
for the same bad input; unifying the error text without deciding this
would silently change one of them.

`select` IS A CORRECTNESS REQUIREMENT, and Q#BP12's citation drifted.
`seat_cursor` is at listview.lua:130, not :64 — :64 is now a name-variant
constant. The constraint holds and is worse than "focus preference":
`seat_cursor` drives `pmacs.editor.move_down()`, which acts on the ACTIVE
window, so an unselected listview panel seats the cursor in the user's
document. That is why the table's `select` differs per adopter —
listview true, compile false, terminal true — and why a uniform value
would look right and break compile's passive output.

TESTS ARE MEASURED BEFORE THE FLIP, NOT AFTER. Two Stage 1 acceptance
tests assert the old default deliberately: acc19 (:1223) opens a
listview with no `display` specifically to seed a DOCUMENT window "so
side-affine placement cannot be vacuous" — the flip breaks its
anti-vacuity guarantee, not merely its assertion — and acc19b (:1308) is
built around a recompile reaching `start_run` with no `display`. The
sweep rule is stated: a test whose SUBJECT is placement asserts the new
default; a test whose subject is compile or terminal behaviour opts out
only when its setup genuinely requires the document window. Mass-adding
`display = "current"` to make suites green would convert a behavioural
change into an invisible one.

Acceptance gains a NEGATIVE criterion (9): omitted `display` still means
document placement for direct dired AND for `pmacs .`. That is the
criterion that catches a well-intentioned "make all four consistent"
change.

Framing only. No code, no flip, no test changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Levi Neuwirth 2026-08-01 18:28:05 -04:00
parent 21de0b2038
commit fa12095873
No known key found for this signature in database
1 changed files with 376 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

376
docs/bottom-panel-stage3-framing.md Normal file
View File

@ -0,0 +1,376 @@
# Framing — Bottom panel Stage 3: the adopter default flip
**Revision 2.** Status: **approved with amendments** (revision 1 → 2
records them). Scouted against `githubsucks/main` @ `000b6cd` (v1.1.0).
**Revision 1 → 2**, all from review and all verified rather than
accepted:
- **Dired is a FOURTH copy of the validator, not merely a fourth
adopter** — and it must keep `"current"` as its default, because the
`pmacs .` path reaches it with no `display` at all (§1.1a). Revision 1
had this as an open question with a leaning; it is now a decision with
a mechanism.
- **Unify narrowly, not wholesale** (§2 Q#S3-1). A shared
`resolve_adopter_display(operation, raw, default)` covering vocabulary,
error text and default policy — with terminal's `window`
mutual-exclusion staying in its Rust wrapper, because the parsers are
*not* identical and pretending otherwise is its own defect.
- **A negative criterion is added** (acceptance 9): omitted `display`
must still mean document placement for direct dired **and** for
`pmacs .`.
- **The suite fallout is named, not just counted** (§1.6a): two Stage 1
tests assert the old default deliberately and must be revised
knowingly.
Stage 3 is **Arc 7's last step**. Stages 1, 2A, 2B-1, 2B-2 and 2B-3 are
all on `main` (#155, #175, #177, #184, #187, #198); the panel is complete
on both frontends and every mechanism this stage needs exists. What
remains is the decision the arc deferred on purpose: **omitting `display`
should mean the panel, not the selected window.**
The parent framing already decided the policy (Q#BP12) and wrote the
acceptance sketch (criteria 56–58). This document re-scouts that plan
against current `main` and records where it has drifted.
---
## 0. Coherence impact (COHERENCE §20)
- **Concern: §14 Coherent Workbench Primitives**, graded *"partial, with
the best trajectory of any concern."* This closes the panel half of
P5. §14's bottom-panel bullet names Stage 3 explicitly as what is
left.
- **§6 Interaction islands — this REMOVES one.** Today every adopter
that wants a panel must say so at each call site, and three separate
code paths decide what silence means. After Stage 3 the policy is the
default and the call sites stop carrying it.
- **Journey steps touched:** none directly, though steps 6 and 9 (LSP
panels, compile output) change where their output lands.
- **Config registry adoption:** none — Q#BP12 is explicit that this is
**not a hidden global setting**. It is a resolved default, not a
preference.
- **Background-work attribution:** none.
- **Enables:** DAP. Q#BP12's adopter table **already contains a
`DAP stack/variables` row**, so this stage settles the debugger's panel
policy before the debugger exists. That is the intended order.
---
## 1. Ground truth (measured at `000b6cd`)
### 1.1 The flip is three sites in two languages
The parent framing says *"Stage 3 is not one line per consumer."* True —
but the sharper reason is that **the option was never parsed in one
place.** Each adopter validates and dispatches `display` itself:
| site | adopter | omission today |
|---|---|---|
| `src/lua_bindings/window_panel.rs:269` | `pmacs.terminal.open` | `None \| Some("current") => AdopterPlacement::Current` |
| `builtin/runtime/listview.lua:235` | listview | `if display == "panel" … else switch_buffer` |
| `builtin/runtime/compile.lua:899` | compile | same, plus an `already_in_panel` special case |
A **fourth** copy validates the same vocabulary without being a
default-flip site: `builtin/runtime/dired.lua:645`. It is the one that
must NOT flip (§1.1a).
`parse_adopter_placement` looks like the shared parser its doc comment
implies, but **it has exactly one caller** — the terminal. listview and
compile each re-implement the same three-value validation in Lua,
including their own copy of the error message.
**The three default-resolution branches are the flip; the fourth
validator is not.** `window_panel.rs:269`, `listview.lua:235` and
`compile.lua:899` all move. Changing only the Rust parser would leave
**both** Lua adopters resolving omission to the current window — a
half-flip that would look done and behave inconsistently per adopter.
Four copies of one rule is also how the next adopter gets it subtly
wrong — and the next adopter is **DAP**, already named in Q#BP12's
table. Hence Q#S3-1's narrow unification.
### 1.1a Dired must NOT flip, and the reason is the golden journey
`dired.lua:645` validates the same `"current" | "panel"` vocabulary with
the same error shape, so it is a fourth copy of the rule. **Its default
must stay `"current"`**, and the mechanism is specific rather than
stylistic:
```lua
pmacs.path.set_directory_handler(function(path, dest)
open_async(path, { dest = dest }, nil, "dired")
end)
```
The `pmacs .` path reaches dired through that slot with **`{ dest =
dest }` and no `display` key at all** — so it resolves by omission. If
dired's default flipped with the others, **`pmacs .` would open the
directory listing in a bottom panel**, which is wrong for journey step
2 and for every subsequent step that navigates from it. Journey Stage
1a made `pmacs .` open a directory at all; putting the result in a
panel would undo the point of it.
This is the difference between an adopter and a surface. listview,
compile and terminal produce *output the user consults*; dired produces
*a document the user works in*, like a buffer. The panel default is
right for the first kind and wrong for the second.
### 1.2 `select` is not cosmetic for listview, and the citation drifted
Q#BP12 requires `select = true` for interactive listview, citing
`listview.lua:64` for `seat_cursor`. **That line is now
`NAME_VARIANT_LIMIT`; `seat_cursor` is at line 130.** The constraint
itself is intact and verified:
```lua
local function seat_cursor(p, line)
...
for _ = 1, target do
pmacs.editor.move_down()
end
```
`pmacs.editor.move_down()` acts on the **active window**. A listview
panel displayed without `select` would seat the cursor in whatever
window is selected — the user's document. `listview.refresh` has the
same property. **This is a data-corruption-shaped bug, not a focus
annoyance**, and it is why the table's `select` column differs per
adopter rather than being uniform.
Compile takes `select = false` deliberately (passive output); terminal
takes `select = true`.
### 1.3 Compile has already been prepared for this stage
`compile.lua:894` carries a comment written for Stage 3:
> Gated on OMISSION, never on an explicit value: `display = "current"`
> is the documented user-facing opt-out from the Stage 3 default flip,
> so it must reach the raw switch even when the previous run was
> panel-placed.
and the condition is already
`display == "panel" or (display == nil and already_in_panel(slot.buf))`.
So compile's *recompile* path already keeps a panel-placed buffer in the
panel on omission. **Stage 3 makes the first run behave like the
recompile.** Re-read this comment before editing: it encodes a
distinction (omission vs explicit `"current"`) that the flip must
preserve, and the `already_in_panel` branch may become redundant.
### 1.4 What Stage 3 owes beyond the flip
Q#BP12's table is a per-adopter contract, not a single switch. For each
of listview / compile / terminal:
- **panel placement** with that adopter's `select` value;
- **`dedicated = false`** — a dedicated panel refuses to host anything
else, and dired Stage 1 already established that `display_buffer` will
not replace a buffer in a slot dedicated to another (Q#BP3 2.iii);
- **quit action**: delete the panel if this adopter created it, restore
the panel it replaced otherwise;
- **visit path onto `display_file` / `display_target`** with `select`
per the table.
`display_file` already exists and is used by dired (`dired.lua:831`,
`:840`) and `default.lua:729`, so the visit half has a proven caller
shape to copy.
### 1.5 Capability fallback still applies, and must be re-proved
The Stage 3 default resolves as a *panel request*, so it passes through
Q#BP13 capability fallback exactly as an explicit `"panel"` does. On a
pre-panel semantic frontend the request degrades, and criterion 57
requires that the degraded path leave **no side parameters and no quit
action on the document window**.
This is the criterion most likely to be quietly wrong, because the
fallback is invisible from the adopter's side.
### 1.6 What is NOT established
- **Nothing has been implemented or measured.** Unlike the distribution
lane, there is no artifact to inspect; the evidence is the existing
suites' behaviour before and after.
- **The blast radius on existing acceptance suites is partly known
now** — see §1.6a for the two named cases. The total is still
unmeasured. Stage 1
shipped the mechanism opt-in precisely so existing suites kept their
meaning. Flipping the default changes where output lands for every
suite that exercises listview, compile or terminal **without** passing
`display`. Criterion 58 says the default-placement suites are
*updated*; how many others move is a measurement this framing has not
taken and the implementation must take first.
- **Interaction with dired.** `dired.lua:18` documents
`opts.display = "current" | "panel"` with **default `"current"`**.
Dired is not in Q#BP12's table. Whether the flip reaches it, or dired
keeps an explicit `"current"`, is Q#S3-2.
---
### 1.6a Two Stage 1 tests assert the OLD default deliberately
These are not collateral damage; they encode intent and must be revised
knowingly.
- **`tests/bottom_panel_stage1_acceptance.rs:1223`** —
`acc19_adopters_place_side_affinely_through_real_entry_points` opens a
listview with **no `display`** specifically to seed the panel buffer
into a DOCUMENT window first, *"so side-affine placement cannot be
vacuous."* After the flip that setup no longer produces a document
window, and the test's own anti-vacuity guarantee is what breaks. It
needs a new way to seed, not a `display = "current"` bolted on.
- **`tests/bottom_panel_stage1_acceptance.rs:1308`** —
`acc19b_recompile_reuses_the_panel_instead_of_duplicating_into_the_document`
is built entirely around a recompile reaching `start_run` with no
`display`. Its subject survives the flip, but its mechanism (`§1.3`'s
`already_in_panel` gate) may not — see Q#S3-3.
**The rule for the fallout sweep:** a test whose *subject* is placement
must assert the **new** default. A test whose subject is compile or
terminal behaviour opts out with `display = "current"` **only when its
setup genuinely requires the document window**. Mass-adding the opt-out
to make a suite green converts a behavioural change into an invisible
one, which is the failure this stage's inverted ordering exists to
avoid.
## 2. Questions
- **Q#S3-1 — DECIDED: unify NARROWLY.** A shared
`resolve_adopter_display(operation, raw, default)` owns exactly three
things: the **vocabulary**, the **error text**, and the **default
policy**. Its four callers are listview, compile, terminal and dired —
the last passing `default = "current"`, which is what makes dired's
exemption a parameter rather than a divergent copy.
**Terminal's `window` mutual-exclusion stays in its Rust wrapper.**
The parsers are *not* identical, and a helper that pretended otherwise
would be its own defect: only terminal accepts a `window` id, and only
it must reject `window` combined with `display = "panel"`.
**One normalization must be named rather than absorbed.** Terminal
reads `spec_table.get::<Option<String>>("display")?`, so a non-string
value raises **mlua's type error before** the custom "unknown display"
message is ever reached. The Lua callers instead `tostring()` whatever
they got and report it inside their own error. These are different
observable behaviours for the same bad input, and unifying the error
text without deciding this would silently change one of them. The
stage must state which it standardizes on and pin it.
- **Q#S3-2 — DECIDED: dired does not flip.** It keeps `"current"` as
its default, expressed as the `default` argument to the shared
resolver so the exemption is visible at the call site rather than
implied by a fourth copy of the parser. §1.1a records the mechanism —
the `pmacs .` handler passes no `display` — and acceptance 9 pins it
from both entry points.
- **Q#S3-3 — does `already_in_panel` survive?** Once omission means
panel, compile's special case may be dead code. **Leaning: measure,
then delete if dead** — but check the explicit-`"current"` path first,
because that arm is what the comment says the gate protects.
- **Q#S3-4 — how many existing suites move?** Unknown (§1.6). This must
be measured **before** the flip, so the diff to acceptance files can be
read as intended-vs-collateral rather than discovered afterwards.
- **Q#S3-5 — is there a user-facing escape beyond per-call `display`?**
Q#BP12 says this is deliberately not a setting. Someone who dislikes
panels has no global opt-out, only per-call `display = "current"`,
which they do not control for builtin commands. **Leaning: accept for
this stage and record it**, since a setting is §11 work and panel
persistence is already blocked on settings persistence.
---
## 3. Bets
- **Bet 1 — the flip itself is small; the suite churn is the work.**
Three dispatch sites, each a few lines. The cost is criterion 58's
per-adopter open→visit→return→quit suites plus whatever §1.6's
measurement turns up.
- **Bet 2 — the capability-fallback criterion (57) is where a defect
hides.** It is invisible from the adopter side and only observable on a
pre-panel semantic frontend.
- **Bet 3 — `select` gets one adopter wrong.** The values differ per
adopter for real reasons (§1.2), and a uniform `select = true` would
look correct and break compile's passive-output behaviour.
---
## 4. Acceptance
Inherits the parent framing's criteria 56–58, made concrete:
1. Omitting `display` from listview, compile and terminal entry points
resolves to the Q#BP12 panel/select policy on a panel-capable grid
**and** semantic frontend.
2. Explicit `display = "current"` preserves each adopter's pre-arc
selected-window behaviour, including compile's raw-switch path.
3. **Per-adopter `select` matches the table** — listview `true`,
compile `false`, terminal `true` — asserted individually, not by a
shared helper that would pass with a uniform value.
4. An interactive listview panel seats its cursor **in the panel**, not
in the previously selected window (§1.2's real failure mode).
5. On a pre-panel semantic frontend the omitted default takes capability
fallback with **no side parameters and no quit action** left on the
document window; visit and `q` remain the existing non-side paths.
6. Per-adopter open→visit→return→quit suites, not a generic helper
(criterion 58), preserving Stage 1's unknown-value rollback
assertions.
7. **The unknown-`display` error still fires before anything is
created** — buffer, session, process or wrapper — for all three
adopters, whichever parser survives Q#S3-1.
8. The count of existing suites whose behaviour changes is **stated**,
and each change is classified intended or collateral — **not
silenced by mass-adding `display = "current"`** (§1.6a).
9. **NEGATIVE criterion — omission still means the document for dired.**
Both entry points are pinned: a direct `pmacs.dired.open(path)` with
no `display`, **and** the `pmacs .` launch path through
`pmacs.path.directory_handler`. Neither may place into a panel. This
is the criterion that would catch a well-intentioned "make all four
consistent" change, and it guards journey step 2.
---
## 5. Parked
- Everything in the parent framing's §6 "Deferred (named)" — left/right/
top side windows, multiple slots, `no_other_window`, manual
hide/show, `display-buffer-alist`-style user rules, panel persistence
(blocked on settings persistence), GPU document splits.
- **A global panel preference** (Q#S3-5) — §11 work.
- **The tree primitive.** Not part of this stage, and the next thing to
scope: §14 grades Tree ✗, and DAP's variables view is its next
would-be inventor.
---
## 6. Gates
The standing `CLAUDE.md` suite, with the touched acceptance suites being
at minimum `bottom_panel_stage1_acceptance`, `bottom_panel_stage2a`,
both `stage2b` daemon/GPU suites, plus the listview, compile-mode and
terminal suites — the last three are where §1.6's unmeasured churn will
land.
---
## 7. Branch plan
One branch, `bottom-panel-stage3`:
1. **Measure first** (Q#S3-4): run the full suite with the flip applied
as a throwaway edit, record which suites move, revert. *The
measurement is the first commit's evidence, not the flip.* Classify
each mover per §1.6a's rule before writing a line of the fix.
2. **Land `resolve_adopter_display`** (Q#S3-1) with all four callers
still passing their CURRENT defaults, so the unification is provably
behaviour-preserving before anything flips. Decide and pin the
non-string normalization here.
3. **Flip the three sites** by changing only the `default` argument at
listview, compile and terminal — dired keeps `"current"` — with
per-adopter `select`.
4. **Per-adopter open→visit→return→quit suites** (criterion 6).
5. **Capability fallback** (criterion 5), the one needing a semantic
frontend.
6. **Update the lane and handoff**; Arc 7 closes.
Step 1 before step 3 is the point: flipping first and reading the
fallout as it appears makes intended and collateral changes
indistinguishable.