Skip to content
Fera Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.

GPUI is gone from the architecture but still normative in 14 places

Источник: dev/fera-research/docs/oc1/001-gpui-residue-after-adr028.md (read-only; сгенерировано scripts/sync-docs.mjs)

GPUI is gone from the architecture but still normative in 14 places

Section titled “GPUI is gone from the architecture but still normative in 14 places”
  • kind: problem
  • area: ui
  • evidence:
    • /home/nikki/dev/fera/project-design/context/ADR.md:961-968 — ADR-028 rejects GPUI: “Upstream GPUI is pre-1.0 with breaking API churn and near-zero documentation (the decisive objection…)”; decision at ADR.md:971 pins Vello + Parley + winit + AccessKit.
    • /home/nikki/dev/fera/project-design/context/ADR.md:996 — “the undocumented-GPUI risk is dropped.”
    • Stale residue (all still normative text, not historical narrative):
      • TECHSPEC.md:33 — layout lists /renderer-gpui/ — Engine axis, nylon-ring cdylib.
      • TECHSPEC.md:266 — same section names the Engine axis renderer-vello. Two different names for one module in one document, 233 lines apart.
      • TECHSPEC.md:295 — “Local UI mechanics … native GPUI Models”.
      • TECHSPEC.md:458 — sequencing step 3: “Elm central loop + minimal GPUI rendering (text-only chat view)”.
      • ADR.md:190 — ADR-008’s own title: “…native GPUI models for local UI mechanics”.
      • ADR.md:194, ADR.md:203, ADR.md:206, ADR.md:210-211, ADR.md:217, ADR.md:220 — ADR-008’s Context/Decision/Consequences are written entirely against GPUI (Model<T>, View/Element trait-object model, “decoupled enough from GPUI internals”).
      • ADR.md:242 — ADR-009 names the Engine axis renderer-gpui.so.
      • ADR.md:571 — ADR-014 “no GPUI context required”.
      • RFC.md:64 — “local GPUI-model UI mechanics are, by design, swappable native modules”.
      • QA.md:101 — “runnable with no GPUI context”.
  • severity: mid

Суть / Substance

Section titled “Суть / Substance”

ADR-028 killed GPUI on 2026-09-30, but only the Status line of ADR-009 was amended (ADR.md:227-231); the GPUI-dependent bodies of ADR-008 and ADR-009, the RFC, the QA gate wording and four places in TECHSPEC still describe GPUI as the substrate. The concrete hazard is not cosmetic:

  1. Two names for the same module (renderer-gpui vs renderer-vello) in the crate layout that commit 575d16e was built from. The real workspace resolved it silently as core/crates/ui-engine-vello (in-process crate, not a dylib at all — see my finding 010).
  2. ADR-008 is the normative decision for where UI state lives, and its “local mechanics = native GPUI Models” carve-out (line 206) is the only place the central/local state boundary is specified. With GPUI gone, that boundary has no defined implementation — nothing in Vello/Parley/winit plays the role of a local reactive model, so hover / tooltip / dropdown state currently has no home. Whoever implements TECHSPEC §6 will either silently invent one or route everything through Msg, violating ADR-008’s intent.
  3. TECHSPEC.md:458 tells the implementer to prove the UI data flow with “minimal GPUI rendering” — i.e. the milestone that validates the whole Elm-loop design is specified against an engine that no longer exists.

Варианты решения (tradeoffs)

Section titled “Варианты решения (tradeoffs)”
  • (A) Rewrite the ADR-008/009 bodies in place. Cleanest, but rewrites accepted records; loses the record of why GPUI was chosen first.
  • (B) Add an ADR-008 addendum + leave bodies. Same pattern ADR-020 already uses (“Naming addendum (2026-09-30)”, ADR.md:801). Preserves history, but readers of the body still hit the wrong text first.
  • (C) Status-line only (what happened for ADR-009). Cheapest, and is demonstrably what produced this drift. Reject.

Предлагаемое решение

Section titled “Предлагаемое решение”
  • (B), plus a corpus-wide “Resolved → see ADR-XXX” sweep of TECHSPEC.md, RFC.md, QA.md — the same protocol README.md:41-45 already mandates for OQ entries (“An OQ resolved becomes an ADR (or an ADR addendum) and the OQ entry is marked Resolved → see ADR-XXX”). TECHSPEC/RFC/QA have no equivalent marker convention; that asymmetry is the root cause.
  • New ADR-008 addendum that (a) supersedes GPUI with the Vello/Parley local-mechanics story, and (b) explicitly names the new home of local UI state (candidate: per-widget state owned by the Engine module’s HoF layer, evicted with the render tree — needs a real decision, not a rename).
  • Normalise the module name to renderer-vello everywhere; renderer-gpui should not survive in a layout section anyone copies from.