Architecture Specification: Real-Time Event-Driven Terminal & TUI Stream Invalidation
1. Executive Summary & Problem Statement
In asynchronous CLI, scheduler, and multi-agent systems, long-running workloads emit continuous lifecycle, progress, and status events. Traditional terminal output models present two critical friction points:
- Line Pollution & Context Scroll-Off: Emitting standard newline-terminated log lines (
\n) for every intermediate tick or percentage delta floods the terminal scrollback buffer, obscuring operator visibility and context for interactive commands. - Polling Latency & TUI Drift: TUI dashboards or terminal harnesses relying on polling loops or periodic queries introduce artificial latency (e.g. 100ms–1000ms delay), lagging behind real-time execution states and creating inconsistent visual state.
The Knowledge Kernel addresses this by introducing the TerminalProgressSubscriber within the reactive callback mesh (cmd/zqk/callback). As an implementation of CallbackSubscriber, it receives event-driven callback entries without polling delay, synchronizes writes under a strict thread-safe mutex, and performs zero-latency in-place stream invalidation using standard ANSI carriage return escape sequences (\r\033[K).
2. Component Architecture & Event Topology
+-----------------------------------------+
| Asynchronous Callback Producer |
| (Scheduler, Subagent, Worker, Command) |
+-----------------------------------------+
|
v
+-----------------------------------------+
| MultiSubscriberDispatcher |
+-----------------------------------------+
| |
+----------------+ +----------------+
| |
v v
+-----------------------+ +-----------------------+
| FileLogSubscriber | | KernelWALSubscriber |
| (Audit Trails) | | (Lifecycle WAL) |
+-----------------------+ +-----------------------+
| |
v v
+-----------------------+ +-----------------------+
| ShockwaveSubscriber | | TerminalProgressSub |
| (Invalidation Bus) | | (TUI Stream Redraw) |
+-----------------------+ +-----------------------+
|
+-----------------+-----------------+
| |
[Sync Inline Write] [Async Channel Buffer]
| |
v v
+-----------------+ +-----------------+
| Mutex Lock | | Worker Loop |
+-----------------+ +-----------------+
\ /
\ /
v v
+-----------------------------------------+
| Atomic Line Invalidation (\r\033[K) |
| Output Target (os.Stderr / io.Writer) |
+-----------------------------------------+
3. ANSI Carriage Return Redraw Protocols
3.1 Line Invalidation Sequence (\r\033[K)
ANSI TUI redraws leverage two atomic terminal control characters:
\r(Carriage Return): Moves the cursor to the first column (column 0) of the current line without advancing down.\033[K(Clear to End of Line): Erases all existing characters from the current cursor position to the terminal margin.
When combined (\r\033[K), subsequent writes completely overwrite previous status or progress lines without leaving ghost remnants from longer previous text lines.
3.2 Live Progress vs. Terminal Completion States
-
In-Flight Progress Events: Events with type
progressor in-progress status omit a trailing newline (\n). The cursor remains at the end of the updated line, ready for immediate in-place overwriting upon the next reactive callback. -
Terminal Completion & Error Events: Terminal events (
completion,error,failed,completed) append a trailing newline (\n). This seals the final state onto the terminal display and positions subsequent stdout/stderr logs or prompts on a clean new row. -
Cursor Line Finalization on Close: When
Close()is invoked onTerminalProgressSubscriber, if the last emitted line did not terminate with\n, a closing newline is emitted to guarantee cursor restoration.
3.3 Plain Text & Non-TTY Fallback
When AnsiEnabled is configured to false (e.g., non-interactive CI environments, redirected log pipes, or dumb terminals), the subscriber disables carriage return control sequences. Every event is written as a clean, newline-delimited log entry (\n), preventing corrupt control characters in file logs.
4. Writer Buffering & Thread-Safe Synchronization
4.1 Synchronous vs. Asynchronous Dispatch
TerminalSubscriberConfig provides flexible dispatch semantics:
| Mode | Configuration | Behavior |
|---|---|---|
| Synchronous | BufferSize == 0 |
Writes occur directly within the calling goroutine's Notify() under a sync.Mutex lock. Zero goroutine overhead, suitable for low-to-medium event volumes. |
| Asynchronous Buffered | BufferSize > 0 |
Notify() dispatches to a buffered channel (chan *CallbackEntry), consumed by a dedicated worker goroutine registered with goroutinelabels. |
4.2 Non-Blocking Delivery & Buffer Saturation Resilience
Under extreme callback bursts, slow terminal outputs (e.g. over remote SSH or blocked pipes) must not block scheduler execution or worker threads.
- If
DropOnFull: true, the subscriber immediately drops overflowing events using non-blocking channel selects (select ... default:), incrementing an atomic drop counter (DroppedCount()). - If
DropOnFull: false,Notify()honors context cancellation (ctx.Done()), exiting cleanly if the parent context cancels while waiting for buffer space.
4.3 Clean Shutdown & Resource Hygiene
The subscriber guarantees zero goroutine or channel leaks:
Close()marks the subscriber closed via atomic compare-and-swap (closed.CompareAndSwap(false, true)).- Active worker contexts are cancelled, and pending events are drained to the writer.
- Worker termination is synchronized using
sync.WaitGroup. Flush()invokes underlying writer flushers (interface{ Flush() error },interface{ Flush() }, orinterface{ Sync() error }).
5. Event Normalization & Status Formatting
TerminalProgressSubscriber formats heterogenous payload schemas into uniform status lines:
[PREFIX] [CATEGORY] Job: <id> | <metrics> | <message>
-
Job Wakers (
[WAKER]): Formats lifecycle and task waker signals:[WAKER] requirement REQ-100 | Status: waking | Waking dependent tasks. -
Progress Events (
[PROGRESS]): Formats execution percentage, step counters, and status messages:[PROGRESS] Job: job-101 | 45.5% | step 9/20 | Compiling package.... -
Completion Events (
[COMPLETE]): Formats successful terminations with elapsed duration:[COMPLETE] Job: job-ansi | Status: completed | Duration: 3.42s. -
Failure Events (
[FAILED]): Formats execution errors and failure messages:[FAILED] Job: job-fail | Status: failed | Error: disk quota exceeded. -
Color Stripping (
StripColors): When enabled, removes all ANSI color and style escapes (\x1b[...m), preserving line-invalidation escape characters while guaranteeing clean output for monochromatic terminals.
6. Verification and Traceability
| Artifact | Location |
|---|---|
| Subscriber Implementation | cmd/zqk/callback/terminal_subscriber.go |
| Unit & Concurrent Test Suite | cmd/zqk/callback/terminal_subscriber_test.go |
| Task / Work Item | BLI-TERMINAL-TUI-STREAM-INVALIDATION |
| Test Case | TST-TERMINAL-TUI-STREAM-INVALIDATION |
| Priority Plan | PRI-TERMINAL-TUI-STREAM-INVALIDATION (Cycle 20) |
| Functional Acceptance Criterion | CRIT-TERMINAL-PROGRESS-DISPATCH |
| Boundary & Error Criterion | CRIT-TERMINAL-NIL-SAFE-DISPATCH |
| Architecture Specification Criterion | CRIT-TERMINAL-TUI-DOC-SPEC |