Development: Implementation Plan From Requirements

#Implementation Plan From Requirements

This note converts the reviewed requirements into a concrete architecture plan. It is intentionally more specific than the older phase summary in implementation_plan.md.

This is the authoritative implementation-planning document for the current requirements-reviewed architecture.

The following documents are summary/reference companions only:

Use this document to answer:

what the target architecture should be
what the current code already does correctly
what the main gaps are
what order the remaining work should happen in

Current Work-Unit Status

WU-1 Modal Snapshot Design: completed and merged
WU-2 Command Schema Redesign: completed and merged
WU-3 Runtime Dispatch Cleanup: completed and merged
WU-4 Executor State Cleanup: completed and merged
WU-5 Tool Execution Completion: completed and merged
WU-6 Diagnostics/Recovery Alignment: completed
WU-7 Final Public API Cleanup: completed
WU-8 Public Execution API Simplification: completed

Follow-Up Optimization Track

The original refactor work units are complete. The next optimization work should be tracked separately:

WU-9 Documentation Information Architecture Cleanup
- Slice A:
  - move canonical project docs into docs/src/
  - make mdBook the main reading surface
  - reduce root AGENTS.md to a short startup map
- Slice A.5:
  - remove duplicated explanations inside the mdBook
  - shorten oversized pages and split them into subtrees
  - improve concision and progressive disclosure
- Slice B:
  - add CMake docs targets
  - move generated docs into build/docs/...
  - update install/export to consume build-tree docs outputs
- Slice C:
  - split Requirements into smaller subtrees
  - start with docs/src/requirements/execution/index.md
  - keep syntax/semantic as later follow-ups
WU-10 Execution Contract Fixtures Step 1
- add human-readable execution contract fixtures for the public ExecutionSession API
- generate actual results and a GitHub Pages review subsite
- current completed skeleton enforces the supported baseline cases: modal_update, linear_move_completed, rejected_invalid_line, fault_unresolved_target, goto_skips_line, and if_else_branch
WU-11 Execution Contract Fixtures Step 2
- extend the same system to asynchronous blocked / resume / cancelled cases

Goal

Move the project to one clear execution-oriented architecture that is requirements-driven:

chunk input -> buffered parse/lower -> buffered executor state ->
normalized execution commands -> runtime interfaces -> resume/cancel

The parser, semantic validation, execution/runtime behavior, and test policy are already reviewed in the requirements documents. This plan maps those decisions onto code and work units.

Target Architecture

1. Syntax/Semantic Front End

Responsibilities:

parse text into structured form
preserve source information
emit syntax/semantic diagnostics
lower accepted text into AIL instructions

Key rule:

syntax/semantic layers must not perform runtime execution decisions

2. Buffered Execution Core

Primary public execution entry point:

ExecutionSession
buffered incremental input
pushChunk(...), pump(), finish(), resume(...), cancel()
Blocked vs WaitingForInput kept distinct

Internal execution core:

StreamingExecutionEngine

Execution semantics:

executor owns control flow, call stack, and incremental target resolution
forward targets wait before EOF and fault after EOF
execution-related state remains explicit

3. Execution IR

AilInstruction remains the executable IR.

Direction:

parser/lowering produces AIL
streaming engine buffers AIL
executor advances through AIL
normalized runtime-facing command data is emitted from execution

4. Runtime Boundary

Two-level split:

IRuntime
- primitive machine/service operations only
IExecutionRuntime
- richer language-level evaluation built on top of IRuntime

General action-command rule:

action submission returns Ready, Pending, or Error
Pending means accepted by runtime, not necessarily physically complete

Requirements already fixed:

every supported modal group is explicit in execution state
all supported modal groups are preserved
emitted commands carry effective modal values for all supported groups

This implies a full modal snapshot model, not a partial ad hoc set of fields.

Current Architecture Assessment

What Already Matches The Target

public execution-session API already exists in execution_session.h
buffered streaming state already exists:
- pending lines
- buffered instructions
- executor reuse
- Blocked / WaitingForInput
AilExecutor already owns:
- control-flow execution
- call stack
- unresolved-target deferral
- runtime-aware stepping
runtime split already exists:
- execution_interfaces.h
- execution_runtime.h
motion/dwell normalization and dispatch already exist
reviewed fake-log/testing pattern already exists

Main Architectural Gaps

1. Command schema is still partial

Current execution_commands.h now carries a baseline explicit modal subset:

motion code
working plane
rapid mode
tool radius compensation
active tool selection
pending tool selection

That is a useful first step, but it still does not satisfy the reviewed requirement that emitted commands carry all supported modal-group values.

Today modal state is split across:

ModalState
ExecutorState
EffectiveModalSnapshot
AIL per-instruction effective fields

This is workable, but it is not yet one clean source of truth.

3. Public execution command model is not finalized

We now have a normalized baseline for motion payloads:

one target object for motion endpoints
one effective snapshot for modal state
no duplicated emitted opcode / modal fields on execution commands

But the model is still not final for:

future tool/non-motion action payloads
full effective modal snapshot

4. Runtime boundary is correct in principle but not fully normalized

The split is right, but the exact inventory of:

executor-direct evaluation
IExecutionRuntime-only semantics
command submission types

still needs one consolidated design pass.

5. Tool execution is still policy-light

Tool execution requirements are reviewed, but current behavior still needs:

explicit command schema
explicit current/pending/selected tool snapshot model
final M6 no-pending-selection policy

6. Diagnostics/recovery contract is reviewed but not yet formalized in API shape

The requirements now include halt-fix-continue behavior for line failures, but the exact edit/reprocess session mechanics are not yet tied cleanly to the streaming/executor API surface.

Direction chosen for WU-6:

keep StreamingExecutionEngine focused on internal execution
provide ExecutionSession as the public editable rejected-suffix recovery API
use a recoverable Rejected state distinct from unrecoverable Faulted

Design Decisions To Apply Next

Add one explicit execution snapshot type, for example:

EffectiveModalSnapshot

It should become the single command-facing modal payload.

It should eventually include all supported groups, not just current motion ones.

Target:

executor keeps canonical modal state internally
normalized commands expose a copied EffectiveModalSnapshot
ad hoc per-command modal subsets are retired where possible

C. Treat AIL as the only execution IR

Do not add a second interpreter path.

Direction:

syntax/semantic -> AIL
buffered streaming engine -> AIL executor
executor -> normalized command builder -> runtime interfaces

D. Keep `IRuntime` primitive

Do not grow IRuntime into a language interpreter.

Keep these on IExecutionRuntime:

richer expression evaluation
richer condition evaluation
parser-limited/context-heavy execution semantics

E. Keep one streaming execution model

Do not intentionally split semantics into:

batch-only execution behavior
streaming-only execution behavior

The buffered streaming engine should be the primary execution path.

Work Graph

R1 Full modal snapshot design
  -> R2 Command schema redesign
  -> R3 Command builder/runtime dispatch cleanup

R1 Full modal snapshot design
  -> R4 Executor state cleanup

R2 Command schema redesign
  -> R5 Tool execution schema/policy completion

R3 Command builder/runtime dispatch cleanup
  -> R6 Diagnostics/recovery API alignment

R4 Executor state cleanup
  -> R6 Diagnostics/recovery API alignment

R5 Tool execution schema/policy completion
  -> R7 Final public execution API cleanup

R6 Diagnostics/recovery API alignment
  -> R7 Final public execution API cleanup