enhancement: REPL preview/state commands and reusable controller (no engine changes)

[rlippmann]

Summary

Track a planned extension that adds deterministic, user-facing command semantics (state, preview|explain, step, profile ...) while keeping the engine contract stable.

This issue is planning/tracking only; no implementation is required yet.

Motivation

We want better observability and automation ergonomics without coupling those concerns to engine internals.

Specifically:

• users should be able to inspect current authoritative state easily
• users should be able to dry-run an input and see what would happen
• these capabilities should be reusable outside REPL (CLI/API/integrations)

Decisions Made

1. Do not change the engine-level Decision contract right now.
2. Keep Decision minimal (kind, state, prompt_to_user).
3. Put observability fields (diff, mutated, command metadata, etc.) in a higher-layer envelope (REPL/CLI/controller layer), not in engine Decision.
4. Preserve backward compatibility:

• bare input in REPL continues to behave as today
• step <input> is explicit alias/symmetry form

5. preview <input> / explain <input> must be deterministic dry-run and must never mutate live state.
6. Diff should be:

• derived from before/after state snapshots
• deterministic and purely structural
• non-authoritative (state remains the source of truth)

7. Profile commands should be thin wrappers around existing export_json / import_json.

Proposed Scope

• state command
• preview <input> / explain <input>
• step <input> explicit form
• profile save|load|list|delete|export|import

Out of Scope

• JSON / machine-readable mode (tracked separately in enhancement: add machine-only JSON output mode for non-interactive REPL #56)

Architectural Direction

Introduce a thin, reusable controller layer (callable outside REPL) that:

• operates on an engine instance
• exposes:
  • apply step
  • preview step (dry-run via cloned state)
  • compute diff (pure helper)
  • profile operations (thin wrappers)

This layer must:

• not introduce new state semantics
• not persist additional hidden state beyond the engine
• not reinterpret directives or decisions

Proposed Rollout

1. Chunk 1:

• state
• preview|explain
• pure diff helper
• tests/invariants (preview no-mutation)

2. Chunk 2:

• explicit step
• profile ...
• tests

Acceptance Criteria

• Engine Decision type remains unchanged.
• Bare REPL input remains backward-compatible.
• preview must not mutate session state (including pending clarification).
• Diff output is deterministic and derived only from snapshots.
• Profile operations use current serialization APIs without introducing a new state schema.

Related

• enhancement: add machine-only JSON output mode for non-interactive REPL #56 (machine-only JSON output mode for non-interactive REPL)