Intelligence Layer — Overview

Most terminal UIs are a bag of heuristics. A magic number says “coalesce resizes after 50 ms.” Another magic number says “show this hint after the user idles for 1.5 seconds.” A third says “switch to a full redraw if more than 40% of cells changed.” The numbers are plausible, the authors meant well, and the system still thrashes the moment a workload drifts off the spreadsheet that produced them.

FrankenTUI takes a different posture: every non-trivial decision inside the frame loop is cast as a statistical problem, solved with a principled estimator, and written to a JSONL evidence sink so you can re-run the decision offline. Thresholds are quantiles, schedules are optimal policies, alerts are test martingales. The numbers become consequences of the data, not tuning dials.

This page is the index to that machinery. Each linked page explains one technique, motivates it against the naive alternative, shows the math, and points at the subsystem that consumes it.

The unifying idea

Five recurring concerns drive the design of every component in this layer:

1. Calibrated uncertainty — a TUI never has more than a few hundred samples of anything. Bayesian posteriors (Beta over rates, Normal-Normal over heights) give usable uncertainty from a handful of observations; frequentist point estimates do not.
2. Anytime-valid testing — the runtime “peeks” at every frame. A fixed-$\alpha$ test breaks under repeated looks. E-processes and conformal prediction keep their guarantees under continuous monitoring.
3. Cost-aware decisions — the cheapest rendering strategy depends on the workload. The diff, presenter, and degradation cascade all pick $\arg\min$ over an explicit cost model rather than a static rule.
4. Bounded starvation — background effects still need to make progress. Smith’s rule with aging gives an optimal weighted-completion schedule plus a provable wait-time bound.
5. Auditable reasoning — every decision emits a ftui-evidence-v1 JSONL record. If the palette ranked the wrong command, the evidence ledger shows exactly which Bayes factors pushed it up.

Map of techniques

Bayesian inference — what to believe

Change detection — when the world shifts

Conformal prediction — calibrated risk

Cross-cutting machinery

Heuristic vs. principled — a side-by-side

// The usual story.
if change_pct > 0.4 {
    full_redraw();
} else {
    dirty_row_diff();
}

// crates/ftui-render/src/diff_strategy.rs
let p = posterior.mean();                // Beta(alpha, beta)
let cost_full  = c_scan * cells_total + c_emit * p * cells_total;
let cost_dirty = c_scan * cells_total + c_row   * (p * rows_total);
let cost_full_redraw = c_emit * cells_total;
let pick = argmin(cost_full, cost_dirty, cost_full_redraw);
// plus 95th-percentile conservative mode and an evidence sink line

Evidence sink — the ground truth for every decision

Every page in this section ends with a “How to debug” subsection that names the JSONL event emitted by that subsystem. The envelope is ftui-evidence-v1 and writes land in FTUI_EVIDENCE_SINK (stdout or file).

# Enable evidence to a file
FTUI_EVIDENCE_SINK=/tmp/ftui.jsonl cargo run -p ftui-demo-showcase
 
# Inspect the last 5 diff decisions:
jq -c 'select(.schema=="diff_decision")' /tmp/ftui.jsonl | tail -5

See runtime/evidence-sink for the envelope schema and the full event catalog in reference/telemetry-events.

How to read this section

What this layer does not promise

Cross-references

• runtime/evidence-sink — where every decision lands as JSONL.
• operations/frame-budget — how the conformal + PI + degradation pipeline cooperates.
• reference/telemetry-events — full schema of every emitted event.