Module ivm 

Incremental View Maintenance (IVM) — delta-propagation DAG for derived render state (bd-3akdb.1).

Overview

IVM maintains computed layouts, styled text, and visibility flags as materialized views updated by deltas only. Instead of full recomputation each frame, changes propagate through a DAG of view operators that transform input deltas into output deltas.

Architecture

  Observable<Theme>   Observable<Content>   Observable<Constraint>
         │                    │                      │
         ▼                    │                      │
  ┌──────────────┐           │                      │
  │  StyleView   │◄──────────┘                      │
  │  (resolve)   │                                  │
  └──────┬───────┘                                  │
         │ Δ(style)                                 │
         ▼                                          │
  ┌──────────────┐                                  │
  │  LayoutView  │◄─────────────────────────────────┘
  │  (compute)   │
  └──────┬───────┘
         │ Δ(rects)
         ▼
  ┌──────────────┐
  │  RenderView  │
  │  (cells)     │
  └──────┬───────┘
         │ Δ(cells)
         ▼
    BufferDiff → Presenter → Terminal

Delta Representation

Updates are represented as signed tuples: (key, weight, logical_time).

• weight = +1: insertion / update (new value replaces old).
• weight = -1: deletion (key removed from the view).
• logical_time: monotonic counter for causal ordering.

This is the standard IVM delta encoding from database theory (Chirkova & Yang, “Materialized Views”, §3.1). It composes: applying Δ₁ then Δ₂ is equivalent to applying their union (with cancellation of opposite signs).

Processing Model

Deltas are processed in topological micro-batches:

1. Collect all input changes since last frame (the “epoch”).
2. Sort the DAG topologically (pre-computed at DAG build time).
3. For each view in topological order: a. Receive input deltas from upstream views. b. Apply apply_delta() to produce output deltas. c. Forward output deltas to downstream views.
4. The final view emits cell-level deltas consumed by the presenter.

If any view’s delta set exceeds a size threshold (heuristic: > 50% of the materialized view size), the view falls back to full recomputation via full_recompute(). This handles the “big change” case efficiently.

Evidence Logging

Each propagation epoch logs an ivm.propagate tracing span with:

• epoch: monotonic epoch counter
• views_processed: number of views that received deltas
• views_recomputed: number of views that fell back to full recompute
• total_delta_size: sum of delta entry counts across all views
• duration_us: wall-clock time for the entire propagation

An evidence JSONL entry is emitted comparing delta size vs full recompute cost per view, enabling offline analysis of IVM efficiency.

Fallback

Setting FRANKENTUI_FULL_RECOMPUTE=1 disables incremental processing and forces full recomputation on every frame. This serves as a baseline for benchmarking and a safety fallback if IVM introduces bugs.

Integration with Existing Infrastructure

• DepGraph (ftui-layout): Used for layout-level dirty tracking. IVM wraps DepGraph as the backing store for LayoutView.
• Observable/Computed (ftui-runtime/reactive): Observable changes feed the IVM input layer. Computed values can be replaced by IVM views for frequently-updated derivations.
• Buffer dirty tracking (ftui-render): RenderView output deltas are translated to Buffer dirty_rows/dirty_spans for the presenter.
• BatchScope (ftui-runtime/reactive): Batched observable mutations naturally align with IVM epochs — one batch = one propagation pass.

Structs

CellKey

Key for render view: identifies a cell position (row, col).

CellValue

Cell value (the output of render computation).

DagEdge

An edge in the IVM DAG, connecting an upstream view to a downstream view.

DagTopology

The static topology of the IVM DAG.

DeltaBatch

A batch of delta entries for a single propagation epoch.

EpochEvidence

Evidence record for a single IVM propagation epoch.

FallbackPolicy

Policy for deciding when a view should fall back to full recomputation.

FilteredListView

IvmConfig

Configuration for the IVM system.

LayoutKey

Key for layout view: identifies a layout node.

LayoutValue

Layout result value (the output of layout computation).

PropagationResult

The outcome of processing a single view during propagation.

ResolvedStyleValue

Resolved style value (the output of style resolution).

StyleKey

Key for style view: identifies a widget’s style slot.

StyleResolutionView

A concrete IncrementalView that resolves styles by merging a base (theme) style with per-widget overrides.

ViewDescriptor

Descriptor for a view in the DAG.

ViewId

Lightweight handle identifying a view in the IVM DAG.

Enums

DeltaEntry

A signed delta entry representing an incremental change.

ViewDomain

The domain of a view in the IVM pipeline.

Traits

IncrementalView

The core trait for incremental view maintenance.

Functions

fx_hash

Compute a fast hash of an arbitrary hashable value.