docs: close quad-backgrounds arc — audit + framing status
Records the 9.1–9.3 scoring and the QB1–QB3 follow-on findings that manual validation surfaced (read-only-mirror sourcing, per-tick whole-file recompute, line-relative glyph offsets). Marks the framing doc CLOSED and retires Phase A finding A8. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
4dd2d7e889
commit
e9bbd1f024
|
|
@ -0,0 +1,89 @@
|
|||
# pmacs-gpu quad-backgrounds audit
|
||||
|
||||
Date: 2026-05-29
|
||||
|
||||
Closes the milestone framed in
|
||||
[`pmacs-gpu-quad-backgrounds-framing.md`](pmacs-gpu-quad-backgrounds-framing.md),
|
||||
which retires Phase A finding **A8** (background-bearing decoration
|
||||
kinds storable but unrenderable). Scope: sessions 9.1 (`Selection`),
|
||||
9.2 (`CurrentLine`), and 9.3 (peer-presence sourcing + the perf and
|
||||
correctness fixes the manual validation forced).
|
||||
|
||||
## Evidence
|
||||
|
||||
| Session | Surface | Evidence |
|
||||
|---|---|---|
|
||||
| 9.1 | `Selection` quad backgrounds | Reused session-7's `QuadRenderer`; added `decoration_kind_to_bg_color` + glyph-extent rect builder + render-order (Q#2 α). Merged before visual validation. |
|
||||
| 9.2 | `CurrentLine` quad backgrounds | Producer emits `CurrentLine` from the active window cursor (Q#1 α); cadence falls out of the M11.4 diff (Q#3 β, no extra state). |
|
||||
| 9.3 | Peer-presence sourcing | pmacs-gpu consumes `PresenceUpdate`; `Selection`/`CurrentLine` washes track the editing peer. Manual validation drove three follow-on fixes (QB1–QB3). |
|
||||
|
||||
## Findings
|
||||
|
||||
| ID | Finding | Category | Class | Resolution |
|
||||
|---|---|---|---|---|
|
||||
| Bet #1 | Multi-line vertex decomposition | Geometric-decomposition | — | Surfaced as **QB3** (worse than predicted: not just multi-line, *any* line past 0). |
|
||||
| Bet #2 | `Selection` ↔ `CurrentLine` overlap precedence | Convention-vs-contract | — | Did not surface as a fix. Alpha-blend in M11.4 sort order (CurrentLine under Selection) reads correctly; no precedence contract needed. |
|
||||
| Bet #3 | `CurrentLine` cadence floods the consumer | Producer-cadence | Small | Structurally right, implementation smaller: the existing M11.4 diff suppresses same-line re-emits; no `last_cursor_line` cache needed. |
|
||||
| QB1 | Per-window `Selection`/`CurrentLine` are inert in a read-only mirror (own cursor pinned at 0, no input path) | State-derivation-location | Structural→resolved | Source the washes from `PresenceUpdate` (the editing peer), consumer-only; wire already flowed. |
|
||||
| QB2 | Daemon recomputes the whole-file projection every tick for the semantic frontend — `scoped_style_spans` runs the tree-sitter query over the entire declared (whole-buffer) viewport + clones the theme, gating TUI input on the shared loop | Producer-frequency | Small (perf) | `StyleGate` (parse-bundle `Arc` + generation + viewport) skips the query on cursor-only ticks; `scoped_decorations` materializes the rope once per call instead of twice. |
|
||||
| QB3 | Background washes blind past line 0: `LayoutGlyph::{start,end}` are line-relative but were compared against whole-buffer byte ranges | Library-API-verification | Small (correctness) | Rebase glyph offsets by `line_byte_offsets[run.line_i]` before comparison. |
|
||||
|
||||
## Predicted vs actual
|
||||
|
||||
| Predicted bet | Result | Count |
|
||||
|---|---:|---:|
|
||||
| #1 geometric decomposition | Surfaced (as QB3) | 1 |
|
||||
| #2 overlap precedence | Did not surface | 0 |
|
||||
| #3 cadence | Surfaced, smaller than predicted | 1 |
|
||||
|
||||
Unpredicted categories that surfaced:
|
||||
|
||||
| Category | Count | Findings |
|
||||
|---|---:|---|
|
||||
| State-derivation-location (read-only mirror has no own cursor) | 1 | QB1 |
|
||||
| Producer-frequency (whole-file recompute per tick) | 1 | QB2 |
|
||||
| Library-API-verification (line-relative glyph offsets) | 1 | QB3 |
|
||||
|
||||
Score summary:
|
||||
|
||||
- Predicted categories surfaced: 2 of 3 (#1 via QB3, #3).
|
||||
- Predicted not surfaced: 1 of 3 (#2 overlap precedence — alpha-blend
|
||||
sufficed).
|
||||
- Unpredicted categories surfaced: 3 (QB1 mirror sourcing, QB2 perf,
|
||||
QB3 glyph-offset space).
|
||||
- Small findings absorbed: 5 (Bet #3, QB1, QB2, QB3, plus the framing
|
||||
doc's already-recorded alpha-visibility tweak).
|
||||
- Structural findings deferred: 0 (QB1 was structural-shaped but
|
||||
resolved consumer-only without a contract change).
|
||||
|
||||
**Methodology note.** The three load-bearing findings were all
|
||||
*unpredicted*. The categorical bets were aimed at the wire-shape and
|
||||
composition surfaces; the real failures were in (a) the read-only
|
||||
mirror's cursor semantics, (b) per-tick producer cost, and (c) a
|
||||
cosmic-text API misread. The last echoes the standing M10.10
|
||||
library-API-verification lesson: glyph-offset coordinate space should
|
||||
have been verified against the cosmic-text source before the first
|
||||
glyph-extent rect builder shipped (session 9.1), not after manual
|
||||
validation in 9.3.
|
||||
|
||||
## Close
|
||||
|
||||
A8 is closed for the foreground+background decoration arc:
|
||||
|
||||
- `Selection`: peer selection renders as a translucent background.
|
||||
- `CurrentLine`: peer cursor line renders as a subtle wash.
|
||||
- Both source from `PresenceUpdate`; own-window decorations stay
|
||||
forward-looking for when pmacs-gpu gains its own input (Phase B).
|
||||
|
||||
Not closed (documented, deferred):
|
||||
|
||||
- `SearchMatch` / `SearchMatchActive`: awaiting a search feature in
|
||||
pmacs core (framing Q#4).
|
||||
- Per-peer stable colors, peer caret glyph + label: single-peer mirror
|
||||
reuses the Selection/CurrentLine colors.
|
||||
- Own-cursor vs peer-cursor merge once pmacs-gpu has input.
|
||||
- Consumer-side per-frame minimap rebuild (cacheable like `StyleGate`)
|
||||
— not load-bearing after QB2; revisit if frame timing shows it.
|
||||
|
||||
Debug aids retained (off by default): `PMACS_GPU_DEBUG_PRESENCE`,
|
||||
`PMACS_GPU_DEBUG_FRAME`.
|
||||
|
|
@ -1,9 +1,11 @@
|
|||
# pmacs-gpu — quad-background framing
|
||||
|
||||
**Status: framing pass; pre-implementation.** Retires Phase A finding
|
||||
A8 (background-bearing decoration kinds storable but unrenderable).
|
||||
Sessions queued: 9.1 = `Selection` backgrounds; 9.2 = `CurrentLine`
|
||||
backgrounds; search backgrounds deferred to a later arc.
|
||||
**Status: CLOSED 2026-05-29.** Sessions 9.1 (`Selection`), 9.2
|
||||
(`CurrentLine`), 9.3 (peer-presence sourcing) all merged; finding A8
|
||||
retired. Scoring + the QB1–QB3 follow-on findings are in
|
||||
[`pmacs-gpu-quad-backgrounds-audit.md`](pmacs-gpu-quad-backgrounds-audit.md).
|
||||
Search backgrounds (Q#4) remain deferred to a later arc. The sections
|
||||
below are the original framing pass, preserved.
|
||||
|
||||
This is the per-milestone framing artifact for the quad-pipeline work
|
||||
that closes Phase A's one deferred structural finding. It inherits the
|
||||
|
|
|
|||
Loading…
Reference in New Issue