pmacs/docs
Levi Neuwirth fa980ef1ba
docs(framing): SS5b revision 15 --- appended means LAST, and cancellation had a race
Answers review of 14. Framing only. Four of the six reverse something
14 asserted, and a green protocol gate would not have caught any of
them.

**"BESIDE `Present`/`PanelPointer`" WAS POSITIONALLY DANGEROUS.**
"Beside" reads as adjacent, and adjacent insertion shifts every
discriminant below it --- the exact hazard the appended-only rule
exists for. Appended means LAST: `PresentMapped` after `Absent`,
`PanelPointerMapped` after `TextInput`, with a diagram so the next
reader cannot re-derive it wrongly. Field order is stated exactly,
`mapping_generation` is a `u64`, ZERO IS INVALID --- it is what a
default-constructed or half-initialised sender produces, so accepting
it would let a peer opt out of the check by sending nothing --- and the
gate reads `PANEL_MAPPING_MIN_VERSION = 25` rather than a literal.

**BLANKET REFUSAL STOPPED THE WHEEL AFTER ONE TICK.** The first
effective document wheel changes `view_top`, which advances the key, so
the next already-queued tick carries the old generation and is refused:
the panel scrolls once and goes dead until the frontend observes the
new frame. Local terminal scrollback has the same shape.

The discriminator is whether the gesture USES its coordinate.
Coordinate-free gestures --- the document wheel, non-reporting terminal
scrollback --- cannot be mis-aimed by a stale mapping and are EXEMPT.
A child-reported wheel is the opposite case: SGR carries row and
column, so a stale one aims an application action at a cell the user
never pointed at, and it keeps the check. Two-tick witnesses added,
because without them a blanket-refusal implementation passes every
single-event row in the matrix.

**CANCELLATION WAS REACTIVE AND LOSES A RACE.** If the replacement
mapped frame reaches the frontend before the physical `Up`, the
producer resets `pointer_held` and SUPPRESSES THE VERY EVENT that would
have cancelled --- so the daemon is never told, the selection stays
armed, and the child keeps holding its button. It is now PROACTIVE,
triggered by the authoritative key advancing while a gesture is
accepted, and the producer must emit a cancellation tail or retain the
latch rather than clearing first.

That needs state 14 assumed and never specified: an ACCEPTED-GESTURE
LATCH recording whether the `Down` was accepted, whether it reached the
child, and the coordinate, button and encoding a release must match.
Two rules fall out and are ruled here --- a stale `Up` with no accepted
`Down` is INERT, and cancellation NEVER reclaims a controller another
frontend has since taken, because a stale gesture must not steal a live
one's terminal.

**THE EXISTING SCREEN GENERATION CANNOT BE THE TERMINAL KEY.**
`Screen::changed()` bumps from 39 call sites including `SetStyle`,
`Bell`, the tab-stop operations, cursor-only motion and `SetTitle`.
None of those change what a coordinate denotes, so keying on it would
cancel a drag every time the child recoloured a character. A dedicated
terminal mapping revision is defined over projected cell identity,
retained-row identity and the per-view scroll anchor --- with those
five events as explicit STABLE CONTROLS, so a reader who later reaches
for the convenient counter fails a test instead of shipping a cancelled
drag.

**G5'S EFFECTS ARE NOT PROVABLE ON THIS BRANCH**, and 14 claimed them.
`gesture_last_content_cell` and the document/terminal replay exist only
on `panel-pointer-replay` (`pmacs-gpu/src/main.rs:2143` there); the
same struct here is at `:2124` with no such field. The obligations are
split in a table. G5a --- that the key advancing RAISES cancellation
--- stays here on purpose: the trigger is this slice's rule, and moving
the whole row out would leave the proactive ruling with no witness in
the slice that introduces it.

P2s: mutation legs split (wrap vs gutter, terminal content vs
scrollback, G5a-c, G8a/b, G9a/b); G7 given a positive-path mutation;
G11 expanded --- exhaustion must publish `Absent`, clear input
authority, cancel any accepted gesture and LATCH, or a stale panel
stays painted and permanently inert; the v26 correction finished at the
gate and old-peer cells (`:573`); and the SS20 impact statement added
--- hardens an existing panel island, no journey grade changes, no
config, no background work.

**And the pin correction is mine to make: it EXISTS**, at
`src/protocol.rs:1975`, in the ROOT crate's test module rather than
under `pmacs-protocol/` or `tests/` --- which is exactly where I
searched. `message.rs:524` was right and the doubt was wrong; the
contrary claim is removed from both records.

Gates: all eleven green under `env -u TMPDIR` with `--protocol`,
log 20260814T180105Z.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
2026-08-20 17:55:21 +02:00
..
active-work.md docs(framing): SS5b revision 15 --- appended means LAST, and cancellation had a race 2026-08-20 17:55:21 +02:00
agent-handoff.md docs(handoff): a timeout wrapper around the gate is not a result 2026-08-20 17:32:34 +02:00
auto-indent-framing.md docs: sync auto-indent review metadata 2026-07-10 15:57:38 -04:00
auto-pairing-framing.md test(edit): PR #110 round 3 — pin raw-byte predicate posture and top-level sets guard 2026-07-12 16:20:01 +01:00
autosave-recovery-framing.md fix(persistence): adopt clears the old owner's skip cache; failing sweeps are loud 2026-07-09 12:06:49 -04:00
bottom-panel-framing.md docs(framing): SS5b revision 15 --- appended means LAST, and cancellation had a race 2026-08-20 17:55:21 +02:00
bottom-panel-stage2-framing.md docs(bottom-panel): record framing revision 7 2026-07-29 22:37:41 -04:00
bottom-panel-stage3-framing.md review round 1: the crdt suite Stage 3 missed, and two stale explanations 2026-08-04 12:08:28 +02:00
ci-crdt-coverage-framing.md review round 2: assert the CRDT capability defaults, not their round-trip 2026-08-01 11:37:19 -04:00
ci-red-signatures.md fix(gate): review round 3 --- canonical ancestry, guard witnesses, and a withdrawn claim 2026-08-13 17:07:55 +02:00
comment-toggle-framing.md docs: comment-toggle framing (Arc 2) 2026-07-09 22:35:35 -04:00
compile-mode-framing.md fix(compile): make overlay teardown atomic 2026-07-14 10:57:14 +01:00
config-registry-framing.md fix(config): reject wrongly-typed spec fields; make trim-on-save buffer-aware 2026-07-21 18:29:18 -04:00
context-menu-framing.md docs: right-click context menu framing + as-built (Q#CM) 2026-06-27 22:19:00 -04:00
cua-typeover-undo-framing.md CUA type-over is a single undo step (Q#U1) 2026-06-15 20:00:53 -04:00
desktop-save-framing.md fix(persistence): reliable daemon gate, unarm, per-pane after-load 2026-07-08 22:27:24 -04:00
destination-capture-framing.md docs: carry the four-plus-one dedication count into the framing 2026-08-10 14:11:43 +02:00
dired-framing.md docs: record dired Stage 1 (#165) as landed 2026-07-25 17:39:27 -04:00
dired-stage2-framing.md docs: dired Stage 2 framing rev 9 2026-07-28 21:09:11 -04:00
discovery-stage1-command-family-framing.md docs(discovery): finalize Stage 1 framing review 2026-07-31 18:28:35 -04:00
discovery-stage2-framing.md docs: record discovery Stage 2 framing approval 2026-08-10 13:52:32 +02:00
distribution-stage1-framing.md docs(release): a tag before the merge does nothing, silently 2026-08-01 14:46:27 -04:00
editing-conveniences-framing.md fix(edit): PR #111 round 1 — scalar-valid UTF-8, per-word capitalize, trim error reporting 2026-07-12 16:34:18 +01:00
folding-framing.md docs(folding): framing rev 5 — record approval + keybinding decision 2026-07-23 09:59:37 -04:00
folding-stage2-framing.md docs(folding): Stage 2 framing rev 4 — address review round 3 2026-07-23 17:25:55 -04:00
full-grid-resync-framing.md docs: the framing said "awaiting approval" after being approved 2026-08-06 15:22:03 +02:00
gate-protocol-build-framing.md docs: gate framing revision 5 --- pin both emitter pairs, correct print-plan 2026-08-09 18:11:14 +02:00
gate-script-framing.md docs: correct a misattributed review round and an unmeasured claim 2026-08-13 21:10:10 +02:00
generated-buffer-immutability-framing.md merge: integrate main after PR 188 lands 2026-07-29 12:28:25 -04:00
git-integration-framing.md docs: narrow the copy-detection claim to the fixture it was measured on 2026-08-09 22:34:19 +02:00
gpu-attach-robustness-framing.md fix(gpu): F-008 fail-fast must actually tear down the session, not just flag it 2026-07-03 17:14:14 -04:00
gpu-chord-forwarding-framing.md docs: GPU general chord forwarding framing + as-built (Q#GC) 2026-07-03 10:05:55 -04:00
gpu-golden-harness-framing.md docs: GPU headless render harness framing + as-built (Q#GH) 2026-07-03 12:15:19 -04:00
gpu-horizontal-scroll-framing.md feat(gpu): horizontal scroll — QoL Stage 5, closing the long-lines arc (#223) 2026-08-08 10:55:49 +00:00
gpu-initial-target-framing.md test(journey): pin the destination commit, and land the doc updates 2026-07-26 17:25:22 -04:00
gpu-invocation-framing.md Record second GPU invocation review closure 2026-07-23 12:40:03 -04:00
gpu-minibuffer-framing.md docs: GPU minibuffer framing + as-built (Q#MB) 2026-06-30 21:03:32 -04:00
gpu-probe-sigint-framing.md docs(framing): record revision 13 approval 2026-08-19 20:52:25 +02:00
gpu-set-font-framing.md fix(font): close stage-2 GPU behavioral findings 2026-07-18 15:29:25 +01:00
gpu-terminal-input-framing.md docs: measure the CI coverage gap and record the vterm as-framed audit 2026-07-25 17:17:23 -04:00
gui-arc-framing.md docs: Q#S1-7 --- Meta/Super moves to Stage 2, in both records 2026-08-11 23:12:04 +02:00
gui-stage1-input-framing.md docs(framing): SS5b revision 15 --- appended means LAST, and cancellation had a race 2026-08-20 17:55:21 +02:00
gui-zoom-framing.md docs(zoom): the ties both round up, they do not oppose 2026-08-06 17:50:03 +02:00
horizontal-scroll-framing.md feat(view): horizontal scroll, text and decorations together 2026-08-07 22:43:17 +02:00
in-buffer-completion-framing.md docs(completion): phase-2 as-built notes (Q#C6 narrowing, window routing, v15 riders) 2026-07-07 19:57:10 -04:00
in-buffer-search-framing.md docs: consolidate in-buffer search framing (substring + regex) 2026-06-27 15:03:31 -04:00
inline-math-framing.md docs: record the inline-math slice (#158) as landed 2026-07-25 18:16:31 -04:00
inline-math-slice-framing.md fix(math): review round 3 — mapping bug, whitespace defect, real MATH gaps 2026-07-24 20:19:40 -04:00
journey-stage1a-framing.md feat(compile): make building discoverable — journey step 9 2026-07-30 21:13:12 -04:00
journey-stage1b1-compile-defaults-framing.md docs(journey): framing revision 2 — close review round 1 2026-07-30 18:40:34 -04:00
journey-stage1b2-lsp-guidance-framing.md docs(journey): framing revision 4 — close review round 3 2026-07-30 21:52:15 -04:00
journey-stage1b3-welcome-framing.md docs(journey): framing revision 4 — close review round 3 2026-07-31 14:55:57 -04:00
json-yaml-framing.md docs: absorption pass at c5f7501 — #209 landed, and six weeks of drift 2026-08-01 13:56:23 -04:00
keybindings.md feat(git): Stage 1 --- *git-status* and *git-diff*, no wire change 2026-08-09 14:43:21 +02:00
kill-ring-framing.md docs: kill-ring framing (Arc 2), rev 3 2026-07-09 20:10:39 -04:00
latex-grammar-math-substrate-framing.md docs(inline-math): commit the parent inline-math framing 2026-07-23 14:06:26 -04:00
lean4-mode-framing.md fix(lean4): count fan-outs where a claim cannot skip the count 2026-07-26 17:15:24 -04:00
locals-query-processing-framing.md docs: record landed locals-query processing 2026-07-22 13:30:07 -04:00
long-lines-framing.md test: the report itself, at a real PTY — and §1.1 was wrong 2026-08-07 19:37:46 +02:00
lsp-file-watch-d3-framing.md feat(lsp): D3 --- the file watcher stops sleeping and walks once per scan (#233) 2026-08-11 14:59:28 +02:00
lsp-file-watcher-framing.md fix(lsp): read the glob form from the pattern, and stop a cancelled scan emitting 2026-08-11 09:00:15 +02:00
lsp-language-coverage-framing.md docs: LaTeX framing revision 3 --- step zero corrected the premise 2026-08-10 10:48:49 +02:00
lsp-panels-framing.md docs(panels): correct as-built accuracy — position encoding landed, refresh drifted refs 2026-07-08 14:29:23 -04:00
lua-bindings-split-framing.md refactor(lua): re-export install_* wiring fns to preserve the public API 2026-07-06 11:57:56 -04:00
macos-ci-signal-integrity-framing.md docs: record Stage 2 in the framing, and fence R3 off from R2's retirement 2026-08-05 13:51:40 +02:00
mcp-for-package-authors.md M9 ship gate 2026-05-09 15:04:23 -04:00
mode-system-wiring-framing.md fix: harden mode acceptance startup 2026-07-22 08:18:18 -04:00
modeline-detection-framing.md docs: record landed modeline detection 2026-07-22 11:30:45 -04:00
multi-language-injections-framing.md fix(injections): PR #122 round 2 — sibling precedence, observable cap, docs 2026-07-15 12:07:21 +01:00
package-author-guide.md feat(statusline): add composable modeline segments at protocol v18 2026-07-21 12:01:25 -04:00
package-manager-hardening-framing.md fix(packages): F-005 must also guard the frozen/lockfile plan path 2026-07-03 19:05:08 -04:00
packages.md Fix CI and Documentation issues 2026-05-04 10:19:19 -04:00
persistence-framing.md docs: persistence framing (Arc 3) 2026-07-08 17:33:25 -04:00
pmacs-gpu-design.md test(font): wire acceptance suite + protocol/design docs (items 2-8, 15) 2026-07-18 11:46:44 +01:00
pmacs-gpu-diagnostic-parity-framing.md framing: pmacs-gpu diagnostic parity — quad squiggles, minimap marks 2026-06-12 10:00:06 -04:00
pmacs-gpu-mouse-deferred-framing.md framing: mouse deferred set — triple-click, Shift-click, minimap jump, edge auto-scroll 2026-06-12 12:12:18 -04:00
pmacs-gpu-mouse-framing.md session M-1 — Pointer wire + daemon byte-space mouse semantics 2026-06-10 13:10:17 -04:00
pmacs-gpu-perline-reshape-framing.md session R — per-line incremental reshape (typing latency floor) 2026-06-10 15:01:51 -04:00
pmacs-gpu-phase-a-audit.md Close pmacs-gpu phase A audit 2026-05-28 12:49:23 -04:00
pmacs-gpu-quad-backgrounds-audit.md docs: close quad-backgrounds arc — audit + framing status 2026-05-29 10:49:21 -04:00
pmacs-gpu-quad-backgrounds-framing.md docs: close quad-backgrounds arc — audit + framing status 2026-05-29 10:49:21 -04:00
pmacs-gpu-scroll-framing.md docs: viewport-scoped rendering + scroll framing (perf) 2026-05-30 10:28:59 -04:00
pmacs-gpu-status-band-framing.md framing: GPU status band — local freshness + v8 StatusFacts 2026-06-12 13:45:12 -04:00
pmacs-gpu-wavy-squiggles-framing.md pmacs-gpu: wavy diagnostic squiggles (Q#W1) 2026-06-15 18:41:56 -04:00
probe-sigint-evidence.md docs(framing): close revision 12 approval blockers 2026-08-19 15:21:35 +02:00
process-signal-diagnostic-completeness-framing.md docs(process): stop overclaiming the pre-kill sample; drop a dead comment 2026-07-30 14:41:50 -04:00
process-signal-tolerance-framing.md docs: frame the PTY terminate diagnostic (revision 4) 2026-07-25 21:12:51 -04:00
process-teardown-stdin-deadlock-framing.md fix(process): arm the setsid dependency, correct the orphan account 2026-07-29 22:54:06 -04:00
project.md Fix PTY final-output drain race 2026-05-04 09:44:30 -04:00
query-replace-framing.md fix(query-replace): pin the session to its origin buffer (wrong-buffer guard) 2026-07-08 17:07:08 -04:00
r8-fixture-boundary-framing.md fix(tests): bound the LSP fixture's project detection — retires R8 (#226) 2026-08-09 08:54:06 +00:00
reap-ledger-silent-failures-framing.md fix(process): scope the escalation claim to ticks, and pin the boundary 2026-07-30 20:41:03 -04:00
repository-audit-2026-07-03.md docs(features): document the Lua feature matrix; drop unreachable compile_error idea (F-002) 2026-07-03 19:54:35 -04:00
resource-op-delete-guard-framing.md fix(lsp): close review gaps in workspace edit reporting 2026-07-29 12:29:50 -04:00
roadmap-2026-07.md docs: record Vterm Stage 3 landing 2026-07-22 19:54:14 -04:00
semantic-frontend-protocol.md feat(statusline): add composable modeline segments at protocol v18 2026-07-21 12:01:25 -04:00
side-quest-backlog.md docs: Q#S1-7 --- Meta/Super moves to Stage 2, in both records 2026-08-11 23:12:04 +02:00
statusline-segments-framing.md fix(statusline): harden narrow-band review edges 2026-07-21 12:43:22 -04:00
tab-width-parity-framing.md docs: link tab-width parity PR 2026-07-22 15:06:10 -04:00
terminal-config-and-copy-mode-framing.md docs: correct the non-adopter attribution and two stale anchors 2026-07-26 16:45:12 -04:00
test-ambient-config-isolation-framing.md docs(framing): record the deliberate departure from the §7 branch plan 2026-07-31 19:46:33 -04:00
theme-faces-framing.md perf(themes): PR #120 round 5 -- O(1) frozen counts via store totals 2026-07-15 11:19:03 +01:00
tree-primitive-framing.md fix(listview): ids must also be unique and not NaN 2026-08-05 23:06:25 +02:00
ux-arc-framing.md docs(ux): as-built for sub-arc 3 + arc close (relative/hybrid, protocol v14) 2026-07-07 10:03:32 -04:00
vterm-framing.md Merge main, and fold #173's a37 findings into the CI-coverage lane 2026-07-26 09:29:42 -04:00
web-grammars-html-css-framing.md docs+test(web): name and pin the @attribute retro-paint (review round 3) 2026-07-23 16:11:47 -04:00
worker-identity-framing.md fix(workers): a safe display-text boundary for purpose and handler names 2026-08-10 14:51:54 +02:00