Decision record · ADR
ADR-0020: Scale the TUI with disposable source-aware in-memory projections
Status: accepted | Date: 2026-07-17
References: RFC-0010, ADR-0018
Context
Section titled “Context”ADR-0018 established a direct, view-only reader of workspace authorities with producer-owned ephemeral operation snapshots and no daemon or persistent index. The initial implementation remains responsive for a small history, but its collection and presentation work scales with every historical record on every refresh: it reparses finalized record bodies, rebuilds repeated display projections and search fields, performs nested identity lookups, redraws even when nothing visible changed, and grants each active server an independent observation budget.
Problem Statement
Section titled “Problem Statement”A long-lived workspace must keep a complete catalog of roughly one thousand top-level records browsable and searchable without turning every display tick into a full replay of immutable history or allowing several unreachable servers to extend one generation once per object. The optimization must preserve file-first authorities, coherent generations, observation age, stale and unavailable semantics, and the existing view-only CLI surface.
Constraints
Section titled “Constraints”RFC-0010 requires a complete continuously navigable record catalog, identity-stable navigation, one display-refresh cadence, a lower-frequency declared-workspace observation, and one fair generation-wide active-server budget. ADR-0018 continues to rule out a daemon, database, event bus, filesystem-watch dependency, and action-hosting TUI. Machine-local caches need no integrity protocol against hypothetical tampering, but they cannot become an evidence or search authority. Operation snapshots change quickly and require current producer-liveness classification; finalized records, declarations, and the append-only journal have different change and observation semantics and therefore must not be forced through one generic cache policy.
Decision
Section titled “Decision”We will retain the direct-reader boundary from ADR-0018 while making collection and presentation disposable, source-aware, and stateful for the lifetime of one TUI process because unchanged historical evidence should not be reparsed and reprojected on every display tick, while no cached value may become a durable authority.
The collector will enumerate record membership on every normal refresh. It will reread non-finalized records on every such refresh and may reuse a finalized record projection only after a successful source change check reports it unchanged. A changed, newly present, or reappearing record returns to the authoritative reader. Collection failures continue through the existing per-object stale and unavailable reconciliation rather than being hidden by the cache.
Declared workspace identity and fully validated definitions will use the lower-frequency schedule defined by RFC-0010:C-REFRESH. The append-only journal will use a stable before-and-after change check around its existing locked reader and will be reparsed in full only when changed. Operation snapshots will remain uncached because each normal refresh must classify current producer liveness even when their JSON is unchanged.
All eligible active-server observations in one generation will consume one shared elapsed-time budget. A retained cursor will rotate the first eligible server across generations so a slow observation cannot permanently starve later servers. An observation not attempted after budget exhaustion retains its prior value and age; an attempted failure retains the existing stale semantics.
Each accepted collector snapshot will produce one immutable presentation generation. That generation will own one canonical display projection per object, per-view ordering indexes, identity-based selection lookup, normalized typed search fields, and the reverse association from record identifiers to journal entries. Views, details, and Find will read that same generation instead of rebuilding independent object projections. Selection will follow stable object identity rather than row position.
Rendering will be invalidated by a newly accepted presentation generation, user input, terminal resize, or the presentation clock rather than by the input-poll loop itself. The cache and presentation generation remain process-local and disposable. They add no workspace file, database, daemon, protocol field, persistent search index, or public configuration surface.
Implementation Notes
Section titled “Implementation Notes”A finalized-record change stamp is an invalidation hint, not an integrity claim. Non-finalized records bypass it because runtime writers update evidence incrementally. Journal change checks surround the existing shared-lock reader so an append racing with a read causes a later reread rather than a permanently missed entry. Source-specific policies remain explicit; this decision does not authorize a generic cache framework or a background workflow engine.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Unchanged refresh work follows record membership, active records, active operations, and changed sources instead of repeatedly parsing all historical record bytes.
- The complete record catalog and Global Find remain available without a persistent index, recent-record cutoff, or paging workflow.
- One presentation generation removes repeated display transformation and gives views, details, selection, and search one coherent identity model.
- A generation-wide observation budget bounds the wall-clock contribution of multiple unreachable servers while fair rotation preserves eventual attempts.
- Existing files remain independently inspectable authorities, and deleting the TUI process discards every derived cache.
Negative
Section titled “Negative”- Cold start still reads the full record catalog, and resident memory remains proportional to the number and displayed content of records.
- Declared workspace identity and definitions can lag their source files by the scheduled interval; explicit observation age and immediate
rrefresh make that delay visible. - Source-aware policies require more collector state than a stateless full rebuild and must preserve failure semantics when cached and fresh objects coexist.
- A process restart loses all reuse and rebuilds the catalog and presentation from authoritative files.
Neutral
Section titled “Neutral”- No record, operation, journal, adapter, or workspace schema changes.
- No new public command, flag, daemon, filesystem watcher, or cleanup lifecycle.
- Further techniques such as viewport-only rendering or structural sharing remain deferred until qualification demonstrates that the accepted design misses its targets.
Alternatives Considered
Section titled “Alternatives Considered”Disposable source-aware collection cache plus one indexed presentation generation (accepted)
Section titled “Disposable source-aware collection cache plus one indexed presentation generation (accepted)”- Pros: Keeps the complete catalog in memory without creating a persisted authority, Makes steady refresh cost follow changed and active sources rather than historical record bytes, Lets views and search share one coherent projection and stable identity map
- Cons: Cold start still reads the complete catalog and memory remains proportional to catalog size
Statelessly reread and rebuild every source on every display tick (rejected)
Section titled “Statelessly reread and rebuild every source on every display tick (rejected)”- Pros: Has the smallest amount of retained reader state
- Cons: Steady CPU and I/O grow with immutable history, Repeated projection and nested lookup work delays input-visible generations
- Rejected because: A complete thousand-record catalog makes unchanged historical bytes the dominant recurring work even though their authority has not changed.
Persist a database or search index beside workspace records (rejected)
Section titled “Persist a database or search index beside workspace records (rejected)”- Pros: Can provide cheap startup queries and rich indexed search
- Cons: Adds schema, migration, invalidation, corruption, and cleanup ownership, Creates a derived store that can drift from file authorities
- Rejected because: The confirmed one-workspace view-only workflow does not justify a second durable authority or service lifecycle.
Show only recent records or divide history into operator-managed pages (rejected)
Section titled “Show only recent records or divide history into operator-managed pages (rejected)”- Pros: Bounds visible rows and reduces per-view work
- Cons: Makes old records and global search incomplete or adds a paging workflow, Treats presentation limits as catalog semantics
- Rejected because: RFC-0010 requires every current top-level record to remain in one continuously navigable and searchable catalog.