docs: frame the GPU terminal double layout-sync defect
Reported symptom: text input in a terminal does not work on the GPU frontend while the TUI is fine. Root cause, measured against a real daemon, a real PTY child, and the real pmacs-gpu attach client: the dispatcher loop applies BOTH terminal-layout syncs to EVERY attached frontend each tick. A semantic session satisfies both conditions -- it has a term_sizes entry from AttachRequest and a semantic terminal declaration -- so the PTY is resized twice per tick forever, because the grid arm runs the TUI placement helper that subtracts a modeline the GPU never draws. The result is a SIGWINCH storm plus screen reflow at tick cadence, which makes an interactive line editor unusable while child output keeps flowing. Measured 730 terminal frames in 20 s for a static screen. Revision 2 answers Q#GT4 from the code rather than deferring it, which changes the fix from a one-line guard into a split of sync_terminal_layout: the grid arm is also the only per-tick controller-liveness release a GPU session gets, and the semantic arm neither performs it nor can be made to, because the buffer-follow snapshot clears the viewport declaration that would drive it. The doc also records three falsified hypotheses, why the Stage 3 real-path acceptance passes on the broken tree, and a COHERENCE.md section 6 citation error (two replica frontends have two different optimistic classifiers; the audit names only one). No code changes in this commit.
This commit is contained in:
parent
46a1b8fc88
commit
9a0df21618
|
|
@ -0,0 +1,415 @@
|
|||
# GPU terminal input — the double terminal-layout sync
|
||||
|
||||
**Revision 2 — approved 2026-07-25. Scouted against canonical `main` @
|
||||
`8c86d34`; implemented on branch `gpu-terminal-input` off `main` @ `46a1b8f`,
|
||||
whose only delta (#161) touches no file on this fix surface. Protocol stays
|
||||
v20.**
|
||||
|
||||
Revision 2 answers Q#GT4 from the code instead of deferring it, which changes
|
||||
the proposed fix from a one-line guard to a **split of `sync_terminal_layout`
|
||||
into a frontend-kind-neutral liveness half and a grid-only geometry half**;
|
||||
rescores B1 as half-false; gives acceptance criteria 2 and 3 a landable
|
||||
observation seam; and corrects four line citations plus the criterion-4
|
||||
rationale. Revision 1's diagnosis is unchanged — the defect, its measurements,
|
||||
and the three falsified hypotheses all stand.
|
||||
|
||||
Reported symptom: *"Text input within the terminal doesn't work on GUI, this
|
||||
is fine in TUI."*
|
||||
|
||||
This is a bug-fix framing, not a feature. It repairs a defect in Vterm Stage 3
|
||||
(#135) that ships on `main` today, and it closes the acceptance hole that let
|
||||
the defect ship: the Stage 3 real-path acceptance drives a terminal session
|
||||
end to end, and *still could not see this*.
|
||||
|
||||
## Summary of the defect
|
||||
|
||||
Every dispatcher tick, the daemon applies **both** terminal-layout syncs to
|
||||
**every** attached frontend:
|
||||
|
||||
```rust
|
||||
// src/daemon.rs:1536-1554 (current main)
|
||||
for frontend_id in &attached_fids {
|
||||
if let Some(size) = term_sizes.get(frontend_id).copied() {
|
||||
editor.sync_terminal_layout(*frontend_id, size); // GRID path
|
||||
}
|
||||
if let Some((buffer_id, size)) = semantic_states
|
||||
.get(frontend_id)
|
||||
.and_then(SemanticRenderState::terminal_viewport)
|
||||
{
|
||||
editor.sync_semantic_terminal_layout(*frontend_id, buffer_id, size); // SEMANTIC path
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
They are written as twins — the comment on the semantic arm even says *"right
|
||||
beside the grid sync"* — but they are applied as **siblings, not
|
||||
alternatives**. A GPU session has an entry in `term_sizes` (its `AttachRequest`
|
||||
carries an initial cell size, and `Resize` events maintain it) *and* a
|
||||
semantic terminal declaration. So both run, every tick.
|
||||
|
||||
The two disagree by construction, and the semantic arm's own doc comment says
|
||||
why:
|
||||
|
||||
> the frontend declared a CONTENT rectangle, so this consumes the size
|
||||
> directly instead of running the TUI placement helper, **which would subtract
|
||||
> a modeline the GPU never drew**.
|
||||
|
||||
That is exactly what the grid arm then does. Measured, on a real daemon with a
|
||||
real PTY and the real GPU attach client:
|
||||
|
||||
```
|
||||
PROBE sync_semantic old=Some(24x80) declared=25x92
|
||||
PROBE manager.resize BufferId(3) 25x92
|
||||
PROBE manager.resize BufferId(3) 22x80
|
||||
PROBE sync_semantic old=Some(22x80) declared=25x92
|
||||
PROBE manager.resize BufferId(3) 25x92
|
||||
PROBE manager.resize BufferId(3) 22x80
|
||||
...
|
||||
```
|
||||
|
||||
The PTY is resized **twice per dispatcher tick, forever**. Each resize is a
|
||||
`TIOCSWINSZ` + `SIGWINCH` to the child and a screen reflow in
|
||||
`TerminalScreen`, so the child gets a SIGWINCH storm at tick cadence and the
|
||||
screen alternates between two geometries. An interactive line editor
|
||||
(readline, zle, fish's reader) redraws on every SIGWINCH, so what the user
|
||||
types is continuously destroyed before it can settle — while ordinary child
|
||||
*output* keeps flowing, which is why the terminal looks alive.
|
||||
|
||||
Measured user-visible effect, real bash `-i` in the real GPU path, typing one
|
||||
character:
|
||||
|
||||
| | frames for a static screen | typed `Z` ever visible at the prompt |
|
||||
|---|---|---|
|
||||
| `main` today | **730** in a 20 s window | **no** |
|
||||
| with the guard | **2** | (see Q#GT5 — a separate question) |
|
||||
|
||||
The TUI is unaffected: a grid session has no semantic terminal declaration, so
|
||||
only one arm ever runs for it. This is a **frontend-kind** defect, which is
|
||||
why it presents as "GUI broken, TUI fine".
|
||||
|
||||
## Ground truth (measured this session, not inferred)
|
||||
|
||||
Everything below was established against `main` @ `8c86d34` with a real
|
||||
daemon, a real PTY child, and the real `pmacs-gpu` attach client. The probe
|
||||
harness is preserved (see "Verification plan").
|
||||
|
||||
### What is *not* wrong — three hypotheses falsified
|
||||
|
||||
Recording these because each is a plausible-looking cause that a future
|
||||
reader (or a review round) will re-propose.
|
||||
|
||||
1. **The GPU's optimistic-CRDT path is not implicated.** The first hypothesis
|
||||
was that a typed character becomes a `CrdtOp` against the read-only
|
||||
terminal identity buffer and is dropped. It does not. Terminal buffers are
|
||||
already marked round-trip — `core.set_round_trip_input(buffer_id, true)`
|
||||
at `src/terminal/session.rs:338`, beside `set_read_only(true)` — so
|
||||
`dispatch_idle_for` returns **false** while a terminal window is focused,
|
||||
the daemon publishes `DispatchIdle { idle: false }`, and the GPU's
|
||||
`daemon_intercepts_keys()` is true. Measured on the wire:
|
||||
`dispatch_idle_in_terminal=false`, `intercept_in_terminal=true`,
|
||||
`input_route=send_key(intercept)`. The optimistic gate is shut.
|
||||
2. **Key transport is not implicated.** The keystroke reaches the daemon,
|
||||
resolves a terminal view key, encodes, and is written to the PTY without
|
||||
error: `PROBE dispatch_key ... terminal_key=Some(TerminalViewKey { .. })`,
|
||||
`PROBE terminal transport encode=Some([90])`, `PROBE after send status=""`.
|
||||
With a `cat` child the byte comes back on screen through the whole real GPU
|
||||
path (`echoed_typed_char=true`).
|
||||
3. **The `pmacs --attach` TUI replica does *not* share the defect.** It gates
|
||||
its optimistic path on `dispatch_idle` alone (`src/attach.rs:843`), and
|
||||
that signal is already correct for terminals per (1).
|
||||
|
||||
### The mechanism
|
||||
|
||||
- `EditorInstance::sync_terminal_layout` (`src/editor.rs:1195`) is the grid
|
||||
path: it runs the TUI placement helper over the frontend's *frame* size.
|
||||
- `EditorInstance::sync_semantic_terminal_layout` (`src/editor.rs:1331`) is
|
||||
the semantic path: it consumes a declared *content* rectangle directly.
|
||||
- Both resolve the same controller and call `TerminalManager::resize` on the
|
||||
same session. Each has a correct `old_size == size` idempotence guard
|
||||
(`src/editor.rs:1239` grid, `src/editor.rs:1360` semantic) — the guards are
|
||||
individually sound and jointly useless, because each arm sees the size the
|
||||
*other* just installed.
|
||||
- `TerminalViewStore::record_view_size` (`src/terminal/view.rs:276-292`)
|
||||
returns `true` for any valid declaration with no unchanged-size dedupe,
|
||||
which is why the semantic arm re-fires every tick against the grid arm's
|
||||
flip rather than settling.
|
||||
- Loop order is grid first, semantic second, so the screen *ends* each tick at
|
||||
the declared size. That is why rendering looks alive while the child is
|
||||
whipsawed — and why a frame-based assertion is the wrong instrument
|
||||
(acceptance criteria 2 and 3).
|
||||
- `TerminalScreen::changed` bumps `generation` per mutation
|
||||
(`src/terminal/screen.rs:1467`), which is why generation advances by
|
||||
**exactly 2** per tick — one bump per resize.
|
||||
- Frame suppression is full-struct equality
|
||||
(`self.last_terminal_frame.as_ref() == Some(&frame)`,
|
||||
`src/semantic_render.rs:882`). It is behaving correctly: the frames really
|
||||
do differ. The churn is upstream, and fixing the churn fixes the frame
|
||||
storm. **No suppression change is proposed.**
|
||||
|
||||
### Why the Stage 3 acceptance could not catch it
|
||||
|
||||
`a37_real_daemon_real_pty_and_headless_gpu_render_one_terminal_session`
|
||||
(`tests/vterm_stage3_acceptance.rs:637`) is a genuine real-daemon +
|
||||
real-PTY + real-wgpu path, and it still passes on the broken tree. Three
|
||||
reasons, each worth keeping:
|
||||
|
||||
1. Its child is `sh` printing 400 rows on a timer. **A frame storm is
|
||||
invisible against a child that legitimately produces ~400 frames**, and its
|
||||
only frame-count assertion is `frames >= 2`.
|
||||
2. Its input step is `client.send_key(...)` called **directly**
|
||||
(`pmacs-gpu/src/main.rs:784-785`), so it pins transport, not routing — and
|
||||
it asserts nothing about the result of that input reaching the child.
|
||||
3. It resizes **once, deliberately**, and asserts the new width comes back.
|
||||
A geometry that oscillates *through* the asserted width satisfies that
|
||||
assertion. This is the project's own "a geometric readout is not a state
|
||||
predicate" lesson (`docs/active-work.md`, bottom-panel round 2) in a new
|
||||
place: `observed_resized_frame` says "a frame at this width arrived", not
|
||||
"the geometry settled at this width".
|
||||
|
||||
## Decisions
|
||||
|
||||
**Q#GT1 — Where does the fix go?** `sync_terminal_layout` is **split**, and
|
||||
only its geometry half is gated by frontend kind. A bare "skip the grid arm
|
||||
for semantic frontends" guard is wrong — see Q#GT4, which establishes that the
|
||||
grid arm is also the only per-tick controller-liveness release. Not by
|
||||
removing `term_sizes` for semantic sessions: semantic key and mouse dispatch
|
||||
hard-depend on it (`src/daemon.rs:2191-2213`).
|
||||
|
||||
The function has three separable concerns
|
||||
(`src/editor.rs:1195-1260`), and they do not split where the name suggests:
|
||||
|
||||
| lines | concern | frontend kind |
|
||||
|---|---|---|
|
||||
| 1199 | `reconcile_panel_layout` (Q#BP2b per-tick defensive) | **neutral** |
|
||||
| 1200-1221 | controller liveness: released when the frontend has no view, or its active window no longer shows that terminal | **neutral** — reads only `core.views` / `core.windows` / the controller, never `term_size` |
|
||||
| 1222-1259 | TUI placement (`window_placements`) + `resize` | **grid only** |
|
||||
|
||||
So the daemon loop becomes: run the neutral half for every attached frontend
|
||||
every tick, then exactly one geometry arm per frontend kind.
|
||||
`sync_terminal_layout` survives as the composition of both halves, so
|
||||
`editor::run`'s in-process loop and `LOCAL` keep byte-identical behavior. The
|
||||
liveness half must run **once** per frontend per tick — reconciliation is
|
||||
idempotent, so a double call is safe rather than wrong, but the loop should
|
||||
not pay for it.
|
||||
|
||||
**The trap inside the split:** the third release, at `src/editor.rs:1226`
|
||||
(no placement found for the window), looks like liveness and is **not** — it
|
||||
is grid geometry. A semantic frontend has no `window_placements` entry at all,
|
||||
so moving that arm into the neutral half would release a GPU session's
|
||||
controller on every single tick. That would be a new defect of exactly the
|
||||
family this framing fixes, so it stays in the grid half.
|
||||
|
||||
**Q#GT2 — Which arm wins for a semantic frontend?** The semantic one,
|
||||
unconditionally. It is the only arm that consumes a *content* rectangle; the
|
||||
grid arm's modeline subtraction is meaningless for a frontend that draws no
|
||||
modeline into the terminal band. A GPU frontend that has not yet declared a
|
||||
terminal viewport gets **neither** arm, which is correct: the terminal keeps
|
||||
the geometry it was opened with until the frontend declares one.
|
||||
|
||||
**Q#GT3 — Is the guard "no semantic state" or "not a semantic session"?**
|
||||
`semantic_states` keyed by frontend id is the same map the semantic arm reads
|
||||
one line later, so the two arms become provably exclusive by construction
|
||||
rather than by two independent predicates that could drift apart. Rejected
|
||||
alternative: keying on the negotiated `semantic_render` capability bit — it is
|
||||
the *same* fact one indirection away, and the pair could then disagree.
|
||||
|
||||
**Q#GT4 — Does anything else in `sync_terminal_layout` need to keep running
|
||||
for a semantic frontend? Yes: the controller-liveness release, and the
|
||||
semantic arm neither performs it nor can be made to.** Revision 1 left this
|
||||
open; the code answers it.
|
||||
|
||||
`release_controller` is called from exactly five sites, all in
|
||||
`src/editor.rs`: the three grid-arm early returns (1210, 1219, 1226),
|
||||
`dispatch_focus(gained = false)` (1189), and `reconcile_panel_layout`'s
|
||||
unsatisfiable-panel path (848). **`sync_semantic_terminal_layout` releases
|
||||
nothing.** When the window has switched away, `semantic_terminal_key` returns
|
||||
`None` (`src/editor.rs:1278` — `window.buffer_id != buffer_id`) and the arm
|
||||
returns `false` without touching the controller.
|
||||
|
||||
Growing a release inside the semantic arm — revision 1's stated fallback for
|
||||
B1 — **cannot work**, and the reason is worth keeping: when a GPU window
|
||||
switches from the terminal to a document, the buffer-follow snapshot clears
|
||||
the viewport declaration (`on_buffer_snapshot_sent` sets
|
||||
`terminal_viewport = None`, `src/semantic_render.rs:574`), so
|
||||
`terminal_viewport()` returns `None` and the semantic arm **stops running
|
||||
entirely** for that frontend. A release placed inside it would never execute
|
||||
in precisely the scenario that needs it.
|
||||
|
||||
Nor do the other two sites cover it: `dispatch_focus(false)` fires on
|
||||
whole-frontend focus loss, not on a window or buffer switch, and semantic
|
||||
sessions are not panel-capable yet (`panel_capable_for` is false for them —
|
||||
`src/daemon.rs:1893-1898`), so 848 never fires either.
|
||||
|
||||
Consequence of shipping revision 1's guard as written: a GPU frontend that
|
||||
switches away from its terminal **holds the controller indefinitely**. Because
|
||||
another frontend's grid sync early-returns on a
|
||||
`controller_view_for_frontend` mismatch, that peer then cannot resize the PTY
|
||||
until it explicitly re-claims. This is why Q#GT1 splits the function instead
|
||||
of gating it.
|
||||
|
||||
**Q#GT7 — The per-tick defensive panel reconcile stays for semantic
|
||||
frontends.** It is the only per-tick pre-paint reconcile the Q#BP2b contract
|
||||
names (`src/editor.rs:822-830`), and today the grid arm supplies it for GPU
|
||||
sessions too. Putting it in the neutral half of the split preserves that
|
||||
exactly. It is harmless-either-way today — semantic sessions have unknown
|
||||
frame geometry until the bottom-panel GPU band lands — but "harmless today"
|
||||
is not a reason to remove a contract's only per-tick enforcement point in a
|
||||
PR about something else.
|
||||
|
||||
**Q#GT5 — Typed characters not echoing by an interactive shell is a
|
||||
*separate* question and is deliberately out of scope.** Measured: with `bash
|
||||
--norc -i` on a `TerminalMode::Raw` PTY, typed characters are not echoed to
|
||||
the screen — **and this reproduces identically in-process**, i.e. on the TUI's
|
||||
own path, where the user reports the terminal works. Because it is not
|
||||
frontend-specific it cannot be the GUI/TUI asymmetry, and folding it in would
|
||||
make this PR two features. It gets its own scout: whether `TerminalMode::Raw`
|
||||
is the right mode for a `pmacs.terminal.open` child, and what pmacs owes a
|
||||
child that expects to own its termios. Named, not silently dropped.
|
||||
|
||||
**Q#GT6 — Protocol impact: none.** No wire shape, no negotiation, no version
|
||||
change. Stays v20.
|
||||
|
||||
## Bets
|
||||
|
||||
- **B1 — SCORED HALF-FALSE before implementation (revision 2).** "Removing the
|
||||
grid arm for semantic frontends removes the storm without removing any
|
||||
behavior a GPU session relies on." The first clause holds (measured). The
|
||||
second is **false**: it also removes the only controller-liveness release
|
||||
and the only per-tick Q#BP2b reconcile a GPU session gets (Q#GT4, Q#GT7).
|
||||
Its stated contingency — "the semantic arm grows the release" — is false
|
||||
too, for a structural reason (`terminal_viewport` is cleared by the very
|
||||
snapshot that signals the switch-away). Hence the split in Q#GT1. Recorded
|
||||
rather than deleted: the failure mode is one a reviewer or a future
|
||||
simplification will re-propose.
|
||||
- **B2.** The user's reported symptom is this defect. *Partially scored: the
|
||||
storm is proven and GUI-only, and its shape (line editor unusable, output
|
||||
still flowing) matches the report. Not fully scored until the user, or an
|
||||
acceptance running the **user's own shell**, confirms typing works after the
|
||||
fix. Q#GT5 is the reason this bet is stated rather than assumed.*
|
||||
- **B3.** No other pair of per-frontend-kind daemon operations is applied as
|
||||
siblings rather than alternatives. *Scored by an explicit audit of the
|
||||
dispatcher's per-frontend loop during implementation — this defect's shape
|
||||
is "twins applied as siblings", and it would be negligent to fix one
|
||||
instance without looking for others.*
|
||||
|
||||
## Deferred (named)
|
||||
|
||||
- Interactive-shell echo on a raw-mode PTY (Q#GT5) — its own scout.
|
||||
- `TerminalFrame` suppression including `screen_generation` in its equality:
|
||||
correct today and load-bearing for correctness, but it means any future
|
||||
content-neutral generation bump re-emits a frame. Recorded, not changed.
|
||||
- The `a37` probe's structural weaknesses beyond what the acceptance below
|
||||
fixes (it still cannot exercise `App::window_event`'s routing, because that
|
||||
logic is inline in the winit handler with no extractable seam). Making GPU
|
||||
key routing testable is a real refactor and belongs to its own lane.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
**The observation seam (revision 2).** Criteria 2, 3 and 6 assert daemon-side
|
||||
state, and `TestDaemon` runs the daemon as a **subprocess**
|
||||
(`tests/common/daemon.rs:90`), so nothing in-process can see it and the
|
||||
scouting instrumentation does not land. The seam that does land: **extract the
|
||||
dispatcher loop's per-frontend terminal-layout step into a named function**
|
||||
that takes `(&mut EditorState, &[FrontendId], &term_sizes, &semantic_states)`.
|
||||
That is required by Q#GT1's split anyway, it makes the grid/semantic
|
||||
exclusivity structural rather than two adjacent `if`s, and it lets an
|
||||
in-process test in the style of the existing `src/daemon.rs` unit tests
|
||||
(3375ff) drive **the real loop body** rather than a re-implementation — which
|
||||
is the a37 lesson applied to this PR's own tests.
|
||||
|
||||
The observable is `TerminalScreen::generation`, reachable through
|
||||
`TerminalManager::snapshot(..).generation`. It advances once per screen
|
||||
mutation (`src/terminal/screen.rs:1467`), so with a quiet child it is a
|
||||
**state predicate**, not a readout: "the geometry settled" is exactly
|
||||
"generation stopped advancing".
|
||||
|
||||
1. On a real daemon + real PTY + real GPU attach, a terminal session that
|
||||
receives no child output produces a **bounded** number of terminal frames
|
||||
(settling to zero new frames once the screen is static) — not one per tick.
|
||||
Fails on `main` with ~730 frames in 20 s; passes with ≤ a small constant.
|
||||
2. Driving the extracted loop body N times against a semantic frontend with a
|
||||
fixed declaration and a quiet child: `TerminalManager::resize` takes effect
|
||||
**exactly once** (generation advances once, then is constant for the
|
||||
remaining N-1 iterations). Fails on `main`, where generation advances by
|
||||
two per iteration.
|
||||
3. After a declaration, `screen_size(buffer)` **equals the declared content
|
||||
rectangle and stays equal** across subsequent iterations — the state
|
||||
predicate, not the "a frame at this width arrived" readout that
|
||||
`observed_resized_frame` provides today.
|
||||
4. A character sent through the real GPU attach client reaches the child and
|
||||
its echo appears in a rendered frame. **This is a keep-working pin, not a
|
||||
fix discriminator: it already passes on today's broken `main`** (falsified
|
||||
hypothesis 2 measured `echoed_typed_char=true`). Pinned with a `cat` child
|
||||
— not because `cat` echoes (termios `ECHO` is off in raw mode; nothing
|
||||
echoes) but because `cat` *copies stdin to stdout*, so the byte comes back
|
||||
exactly once, with no line discipline and no double echo to disambiguate.
|
||||
5. A grid (TUI) session's terminal resize behavior is **unchanged** — pinned
|
||||
against the existing Stage 2 real-TUI PTY smoke, which must stay green
|
||||
without modification.
|
||||
6. A semantic frontend whose window stops showing the terminal **releases its
|
||||
controller** (Q#GT4), pinned through the extracted loop body — driven by an
|
||||
actual buffer switch, not by calling the release directly. This one bites
|
||||
against revision 1's guard as well as against `main`.
|
||||
7. End-to-end SIGWINCH count through the real PTY: a child trapping `WINCH`
|
||||
and printing a **fresh distinct breadcrumb per signal** (`WINCH 1`,
|
||||
`WINCH 2`, …) shows a bounded count. The distinctness is load-bearing —
|
||||
the established PTY-paint trap is that cell diffing skips both spaces and
|
||||
already-matching cells, so a repeated identical marker can assert nothing.
|
||||
8. Bite-verified: reverting the split fails 2, 3, 6 and 7 specifically.
|
||||
Criteria 1 and 7 fail against `main`; criterion 6 fails against **both**
|
||||
`main` and revision 1's guard, which is the point of keeping B1's
|
||||
half-false score on the record.
|
||||
|
||||
Criteria 1, 2 and 7 are deliberately expressed as **quiet-child** assertions,
|
||||
because the existing acceptance's chatty child is exactly what hid this.
|
||||
|
||||
## Coherence impact (`COHERENCE.md` §20)
|
||||
|
||||
- **§2 golden journey, step 8 ("Open a terminal")** — currently graded *"Works
|
||||
but undiscoverable"*. On the GPU frontend it does not work; this restores
|
||||
the step for the frontend the document calls the more capable one. Priority
|
||||
1 explicitly treats journey regressions as release blockers.
|
||||
- **§16 Productize the Semantic Frontend Architecture** — graded *strong*,
|
||||
with "graceful per-frontend degradation is practiced, not aspirational" as
|
||||
its evidence, citing per-frontend fold projection. This defect is the
|
||||
counter-example: a per-frontend-kind operation applied to both kinds at
|
||||
once. The section's claim survives, but the audit should record that the
|
||||
practice is enforced by convention, not by structure — two arms that must be
|
||||
alternatives are currently just two adjacent `if`s. Q#GT1's extracted loop
|
||||
body makes this one structural; the audit note should say the *pattern* is
|
||||
still convention-enforced everywhere else (B3).
|
||||
- **§6 Eliminate Hardcoded Interaction Islands** — the audit's row 6 note that
|
||||
the GPU optimistic classifier "is kept honest by `dispatch_idle_for`" is
|
||||
**confirmed correct** by this investigation (falsified hypothesis 1), and the
|
||||
§6 citation `crate::optimistic::classify_key` should be corrected: that
|
||||
symbol is `src/optimistic.rs`, the **`pmacs --attach` TUI replica's**
|
||||
classifier. The GPU's separate, unrelated classifier is
|
||||
`optimistic_insert_text` / `optimistic_crdt_insert` in
|
||||
`pmacs-gpu/src/main.rs`. Two replica frontends, two classifiers; the audit
|
||||
conflates them.
|
||||
- **§19 Product Coherence Acceptance Tests** — this is a concrete instance of
|
||||
the section's thesis. Every subsystem test passed; the defect lives in how
|
||||
two correct subsystems compose per frontend kind. Criterion 1's quiet-child
|
||||
shape is the transferable technique.
|
||||
- No interaction island added, no config registry surface, no background-work
|
||||
attribution change.
|
||||
|
||||
## Verification plan
|
||||
|
||||
Full gate suite per `CLAUDE.md`, plus:
|
||||
|
||||
- `cargo test --features crdt --test vterm_stage3_acceptance` (the suite this
|
||||
repairs) and `--test vterm_stage2_acceptance` (the TUI no-regression pin).
|
||||
- `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`.
|
||||
- The scouting harness is preserved and should be re-run against the branch:
|
||||
a quiet-child variant of the `a37` probe plus daemon-side resize tracing,
|
||||
saved as `scratch_gui_terminal_input.rs`, `scratch_inproc_input.rs`, and
|
||||
`gui-terminal-probe-instrumentation.patch`. The instrumentation is scratch;
|
||||
the acceptance criteria above are what lands.
|
||||
- Manual confirmation with the user's own shell (fish) in a real GPU window,
|
||||
since B2 is not fully scored by any automated test (Q#GT5).
|
||||
|
||||
**Ops.** This doc is currently untracked in a detached-HEAD worktree
|
||||
(`../pmacs-gui-term-input`), so it does not travel. On approval it becomes the
|
||||
branch's first commit before any implementation, per the standing workflow —
|
||||
no cross-machine expectation should attach to it until then.
|
||||
Loading…
Reference in New Issue