Crucible State Machine — Phase 2: Visual Editor + Scenario Builder (deferred)

[joshua-temple]

Status: Deferred implementation, committed architecture. No timeline for the UI itself — but it is the back half of an architecture v1 builds the front half of, not a speculative add-on. Revisit after v1 has stabilized.

The hard requirement that shaped v1 was: a machine must be authorable either by code or by a WYSIWYG UI, fully decoupled. v1 discharges that requirement by making the definition IR canonical and behavior a named-ref + params registry (see the Overview and Kernel Core discussions). Given that, the UI is just a third front-end alongside the Forge DSL and LoadFromJSON: it emits the same IR JSON, and the host — which already holds the registry — binds it via Provide. The UI never invents behavior; it assembles structure and wires up engineer-provided named behavior from a palette.

Phase 2 is therefore a UX layer over an existing contract, not a kernel change. The kernel does not change to enable it.

The two components

1. Visual state machine editor. A browser UI that renders the IR — states, transitions, ownership swim lanes — and lets the user author it. Engineers and stakeholders inspect and edit the definition without reading Go: click a state to see its entry/exit/onDone actions and owner; click a transition to see its event, guard refs, effect refs, and synchronization mode. Guards and effects are chosen from the registry palette — the named behavior the host already registered — with a form for each ref's params. The editor's output is IR JSON; nothing else.

2. Stakeholder scenario builder. Lets a non-engineer construct an event sequence against a machine without writing code:

   • Pick an entity type and starting state.
   • The server runs PlanPath and proposes a sequence.
   • The user edits it (drop events, insert others, reorder).
   • The UI submits the scenario JSON.
   • The server runs it against a harness and returns a trace.
   • The UI renders the trace as an animation over the machine graph.

The Trace is the unifying primitive

The Trace renders past state, and it is also the substrate users edit to author new runs. The whole loop is JSON in, JSON out:

flowchart TD
    S[Server<br/>Machine IR JSON]
    UI[Visual Editor]
    SC[User authors scenario]
    SS[Server runs scenario via the harness]
    TR[Trace JSON returned]
    UIR[UI renders trace overlay]

    S -->|machine.json| UI
    UI --> SC
    SC -->|scenario.json| SS
    SS --> TR
    TR --> UIR
    UIR -->|edit and resubmit| SC

    style S fill:#dbeafe,stroke:#1e40af
    style UI fill:#fef3c7,stroke:#b45309
    style SS fill:#dcfce7,stroke:#15803d

Loading

The IR is the contract: Machine IR -> UI -> Scenario -> Server -> Trace -> UI.

Why deferred

The architecture is committed in v1; the UI implementation is deferred until v1 stabilizes:

• The machine definition and IR schema must settle (no structural churn) before building rendering/editing UX on top.
• The IR + registry must be exercised in real code use before the server-side editor API is worth building.
• The Trace format must be validated by real usage before a scenario builder can replay it faithfully.

Building the UI before v1 stabilizes means rebuilding it when v1 changes. The deferral is cost-avoidance on the front-end, not a gap in the contract — the contract ships in v1.

What v1 already builds (the front half)

These are v1-core deliverables — not "doors left open." Because they ship in v1, the UI is an authoring surface over an existing contract rather than a from-scratch effort:

v1-core deliverable	Phase 2 usage
Canonical IR JSON (ToJSON / LoadFromJSON)	The editor reads and writes this — its only output.
Named-ref + params registry + Provide	The editor's behavior palette is the registry; binding is Provide.
Lossless round-trip (conformance pillar)	Guarantees a UI-authored machine behaves exactly like a code-authored one.
ToMermaid() / ToDOT()	Fallback static rendering; committed docs/ artifacts.
Scenario JSON + RunAgainst	The scenario builder constructs, submits, and runs these.
Trace JSON	The scenario builder receives and renders these.
PlanPath	Server proposes an initial event sequence to edit.

The only genuinely new work in Phase 2 is the front-end itself — rendering, editing UX, hosting. The data contract, the binding model, and the correctness guarantee all exist in v1.

What is TBD when Phase 2 starts

None of the following is decided — they are open questions for a future scoping session, not inputs:

• Frontend stack (React, Svelte, …).
• Rendering library (D3, Cytoscape, a custom SVG renderer) — each trades off differently for HSM swim-lane rendering.
• Hosting and auth — developer-only, behind SSO, or broader access.
• Scenario persistence — are saved scenarios stored, where, by whom.
• Deployment model — static site, backend-for-frontend, or standalone service.

Sequencing

v1 ships
   v
v1 stabilizes (>= 1 release cycle with no kernel changes)
   v
Phase 2 scoping session
   v
Phase 2 implementation (timeline set at scoping)

No Phase 2 work starts before v1 stabilizes. The scoping session is the gate.

---

Crucible State Machine series: Overview & Roadmap · Kernel Core · HSM · Path Planning · JSON / Mermaid / DOT · Evolution Guide · Conformance · Phase 2