Skip to content

docs(salvage): preserve orphan WIP for ADR-0004 and open-questions #448

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xuepoo merged 1 commit into from
Oct 13, 2026
Merged

docs(salvage): preserve orphan WIP for ADR-0004 and open-questions #448

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions docs/decisions/adrs/ADR-0004-upstream-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,9 @@ Advisory-ignore policy (mirrors the same CI job):
- `RUSTSEC-2026-0192` (`ttf-parser`, unmaintained, winit/Metal paths) and
`RUSTSEC-2024-0436` (`paste`, unmaintained) are enumerated as ignores in
both `deny.toml` (`[advisories].ignore`) and the `cargo audit --ignore`
step until upstream replacements land, composing with rule 4.
step until upstream replacements land, composing with rule 4. Note that
`fontdb 0.24` (Issue [#1692](https://github.com/bitty-terminal/bitty/issues/1692), CTX-0993) vendors its query parser and drops the fontdb edge
to `ttf-parser`; the ignore remains scoped to winit/sctk/ab_glyph paths.
- Ignore entries are visible enumerations, not standing waivers: they are
re-checked as part of rule-4 maintenance and removed when a replacement
lands.
Expand All @@ -110,13 +112,13 @@ the implemented supply-chain gate today.

### Decisions per candidate

| Candidate | Decision | License check | Rationale |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| VT parsing: `vte` vs `alacritty_terminal` vs `wezterm-term` | **Adopt `vte`** (alacritty/vte, ~0.15.x) inside `bitty-vt` behind the crate's own API; reject `alacritty_terminal` and `wezterm-term` wholesale | Apache-2.0 — compatible | Terminal state machines are Core semantics (strategy table: own directly). `vte` provides only a state-machine table + `Perform` trait, which maps exactly onto the parser→`TerminalAction` split in the Architecture Overview. `alacritty_terminal` and `wezterm-term` bundle grid/state/replay opinions that would contaminate Terminal Truth ownership and are hard to partially adopt. If `vte` proves insufficient, escalate to a narrow synchronizable fork of its tables only. |
| PTY: `portable-pty` | **Wrap** (wezterm/wezterm `portable-pty`, ~0.9.x) behind `bitty-pty`; do not expose its types | MIT — compatible | Cross-platform Unix/ConPTY handling is domain infrastructure where upstream reuse beats reimplementation, but process lifecycle, backpressure, and security limits are Bitty-owned invariants, hence wrapper not raw adoption. Fallback if unmaintained: extract to owned fork under rule 3. |
| Windowing/input: `winit`, `crossterm` | **Adopt `winit`** (~0.30.x) inside `bitty-platform`; **do not adopt `crossterm`** as a runtime input path | Apache-2.0 — both compatible | `winit` is the maintained cross-platform window/event-loop baseline matching GPU rendering. `crossterm`'s alternate-screen model conflicts with owning a full renderer and terminal emulation; it may be used in dev tooling/tests only, never in shipped binaries. |
| Rendering/fonts: `wgpu` vs `skia-safe` vs `crossfont` | **Adopt `wgpu`** (~25.x line) in `bitty-render`; **wrap `crossfont`** for rasterization behind the glyph cache; **reject `skia-safe`** | wgpu Apache-2.0/MIT dual; skia-safe MIT but binds Skia (BSD-style with ICU components); crossfont Apache-2.0/MIT — all license-compatible; rejection is architectural | `wgpu` gives Vulkan/Metal/DX12/GL abstraction without a C++ monolith; Skia adds a large C++ supply chain and text-stack opinions Bitty does not need. `crossfont` stays wrapped because font discovery/rasterization policy (fallback, shaping hooks) is Core presentation semantics. Shaping (HarfBuzz binding) is deferred to the text RFC and enters only behind the same wrapper. |
| Lua: `mlua` vs `piccolo` | **Wrap `mlua`** (LuaJIT disabled; stock Lua 5.4 backend initially) inside `bitty-plugin-host`; **track `piccolo`** (~0.3.x) as a watch-list candidate | mlua MIT — compatible; piccolo MIT — compatible | Config and plugin VMs need mature bindings plus sandboxing primitives now; `piccolo`'s pure-Rust stackless VM is attractive for memory accounting/gc-arena isolation but still experimental, so it cannot be the P0 runtime. Re-evaluate piccolo at the plugin-isolation RFC (OQ-014); migration cost is contained because Lua enters only behind the host wrapper. Refined 2026-09-20: the plugin-VM successor path is now Phodopus, a sandbox-first fork of `piccolo`, per [ADR 0012](ADR-0012-phodopus-runtime.md); the accepted `mlua` wrap decision above is unchanged. |
| Candidate | Decision | License check | Rationale |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| VT parsing: `vte` vs `alacritty_terminal` vs `wezterm-term` | **Adopt `vte`** (alacritty/vte, ~0.15.x) inside `bitty-vt` behind the crate's own API; reject `alacritty_terminal` and `wezterm-term` wholesale | Apache-2.0 — compatible | Terminal state machines are Core semantics (strategy table: own directly). `vte` provides only a state-machine table + `Perform` trait, which maps exactly onto the parser→`TerminalAction` split in the Architecture Overview. `alacritty_terminal` and `wezterm-term` bundle grid/state/replay opinions that would contaminate Terminal Truth ownership and are hard to partially adopt. If `vte` proves insufficient, escalate to a narrow synchronizable fork of its tables only. |
| PTY: `portable-pty` | **Wrap** (wezterm/wezterm `portable-pty`, ~0.9.x) behind `bitty-pty`; do not expose its types | MIT — compatible | Cross-platform Unix/ConPTY handling is domain infrastructure where upstream reuse beats reimplementation, but process lifecycle, backpressure, and security limits are Bitty-owned invariants, hence wrapper not raw adoption. Fallback if unmaintained: extract to owned fork under rule 3. |
| Windowing/input: `winit`, `crossterm` | **Adopt `winit`** (~0.30.x) inside `bitty-platform`; **do not adopt `crossterm`** as a runtime input path | Apache-2.0 — both compatible | `winit` is the maintained cross-platform window/event-loop baseline matching GPU rendering. `crossterm`'s alternate-screen model conflicts with owning a full renderer and terminal emulation; it may be used in dev tooling/tests only, never in shipped binaries. |
| Rendering/fonts: `wgpu` vs `skia-safe` vs `crossfont` vs `harfrust` | **Adopt `wgpu`** (~26.x line) in `bitty-render`; **wrap `crossfont`** for default rasterization behind the glyph cache; **wrap `harfrust` + `swash` + `fontdb`** for complex text shaping and ligatures; **reject `skia-safe`** | wgpu Apache-2.0/MIT dual; skia-safe MIT but binds Skia; crossfont Apache-2.0/MIT; harfrust Apache-2.0/MIT; swash Apache-2.0/MIT; fontdb MIT — all license-compatible; rejection is architectural | `wgpu` gives Vulkan/Metal/DX12/GL abstraction without a C++ monolith; Skia adds a large C++ supply chain and text-stack opinions Bitty does not need. `crossfont` stays wrapped as the production default rasterizer. Pure-Rust HarfBuzz text shaping stack (`harfrust` 0.14 + `swash` 0.2 + `fontdb` 0.24) is adopted behind `bitty-render::shaped` under Issue [#1666](https://github.com/bitty-terminal/bitty/issues/1666) / CTX-0952, closing OQ-073 per the accepted [Ligature Decision](https://github.com/bitty-terminal/bitty-terminal-docs/blob/main/specifications/ligature-decision.md); `fontdb 0.24` (#1692, CTX-0993) vendors its query-time parser and drops external `ttf-parser`. |
| Lua: `mlua` vs `piccolo` | **Wrap `mlua`** (LuaJIT disabled; stock Lua 5.4 backend initially) inside `bitty-plugin-host`; **track `piccolo`** (~0.3.x) as a watch-list candidate | mlua MIT — compatible; piccolo MIT — compatible | Config and plugin VMs need mature bindings plus sandboxing primitives now; `piccolo`'s pure-Rust stackless VM is attractive for memory accounting/gc-arena isolation but still experimental, so it cannot be the P0 runtime. Re-evaluate piccolo at the plugin-isolation RFC (OQ-014); migration cost is contained because Lua enters only behind the host wrapper. Refined 2026-09-20: the plugin-VM successor path is now Phodopus, a sandbox-first fork of `piccolo`, per [ADR 0012](ADR-0012-phodopus-runtime.md); the accepted `mlua` wrap decision above is unchanged. |

All versions above were verified against crates.io/GitHub at authoring time;
the implementing task re-verifies and pins exact versions.
Expand Down
Loading
Loading