Execution Engine

This page describes the target architecture for dappTerminal's execution core and the remaining work required before shipping sequential pipelines and multi-surface (CLI + GUI) support.

Sources: notes/notes_feb14.md, notes/CLI-PARSER-PLAN.md, notes/sequential-command-implementation-plan.md

---

Core Position

The current product direction is valid: CLI-first, GUI later.

The correction is architectural:

• The CLI should be a client of the runtime, not the runtime itself.
• The business logic source of truth should be a headless execution core.

Unix analogy:

• Kernel — execution/runtime engine (headless, typed, testable).
• Shell — terminal adapter (text parsing + rendering).
• Desktop — visual adapter (swap windows, provider UI, charts, etc.).

---

Current State (March 2026)

Today, src/components/cli.tsx is simultaneously:

• The text parser
• The command resolver
• The execution engine
• The transaction signing orchestrator
• The history manager
• The tab state manager

This works for a single UI surface but still couples runtime and rendering concerns.

---

Hardening Progress for Pipeline DSL

Status of the February hardening blockers:

Blocker	Status	Notes
Handler return channel	Largely resolved	CommandHandler<T> now returns either an Intent or void for intent-backed commands.
Handler path bypasses history updates	Resolved	Dispatch flow was fixed so validation and execution errors are separated and history handling is consistent.
Global lock is not a scheduler	Partially resolved	Per-tab queue processing exists; full headless scheduler extraction is still pending.
Parser too primitive for DSL grammar	Resolved for single commands	Dedicated parser + contract validation pipeline is complete; pipeline parser layer is still pending.
No execution-scoped variable store	Open	Planned in the sequential pipeline implementation.

---

Completed Foundations

The following pieces are now implemented and stable:

1. Parser + validation boundary: raw input -> parse -> rho resolve -> applyContract -> run
2. Non-throwing parser diagnostics surfaced as warnings.
3. Contract validation executed before command run() so validation failures are not misclassified as runtime failures.
4. Intent-driven confirm/cancel execution flow in CLI with pendingIntent and step status updates.
5. Per-tab queue behavior sufficient for intent confirmation pauses and ordered command processing.

---

Target Architecture

ExecutionEngine (headless)

Responsibilities:

• Resolve command + protocol binding.
• Execute command and handler lifecycle.
• Maintain execution context and history.
• Emit structured events.
• Own queue and scheduling semantics.

Interface Adapters

CLI Adapter (src/components/cli.tsx)

• Text parser and prompt interaction.
• Subscribes to runtime events and renders terminal output.
• No business logic — only rendering and input.

Desktop/UI Adapter (future)

• Typed input forms and visual flow controls.
• Subscribes to the same events for graphical presentation.
• Calls the same ExecutionEngine as the CLI.

Outcome: No duplicated business logic between terminal and GUI. Visual components become first-class clients of the same runtime.

---

Remaining Work

Before sequential pipelines ship:

1. Add a dedicated pipeline parser layer for && and => $var.
2. Add PipelineContext variable storage and interpolation ($name, $name.field, $_).
3. Extract single-command vs pipeline execution helpers from cli.tsx.
4. Normalize chainable pipelineOutput shapes for high-impact write commands.
5. Gate rollout behind the sequentialPipelines feature flag.

See Guides: Pipeline DSL for the full design specification.

---

Design Guardrails

1. UI must never bypass the execution engine for protocol operations.
2. Text parsing remains CLI-specific; the runtime API remains typed.
3. Plugin handlers should return structured outputs, not UI-specific side effects.
4. Logging must be gated (process.env.NODE_ENV === 'development'), never ad-hoc runtime noise.

---

Why Headless Extraction Still Matters

Even with parser and intent hardening complete, runtime and UI remain tightly coupled in cli.tsx. Extracting a headless ExecutionEngine remains the long-term path to:

• reuse across CLI and GUI,
• simpler integration testing,
• cleaner sequencing guarantees for advanced pipelines.