Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

Rail Control Plane (UI + Engine Projection)

Intent

  • Rail is the flattened, typed projection of the execution DAG; every segment has input/output hashes, cache state, backend, determinism, and parents.
  • Selection on the rail scopes the Studio: upstream = builder, downstream = analysis/outcomes.
  • Cache state reflects engine reality (clean/dirty/computing/unsupported/error) and records last recompute result (cache_hit/changed/failed).

Current Implementation (Phase 1)

  • New model: RailSegment, RailGraph, CacheState, StageKind, RailSelection (src/helix/studio/rail_model.py).
  • Central store: RailStateStore publishes graphChanged, selectionChanged, segmentStatusChanged, recomputeRequested, recomputeDownstreamRequested, recomputeResultChanged and owns the inflight state machine (begin_compute / end_compute / fail_compute with inflight ids + timestamps).
  • UI spine: RailControlWidget added above center tabs; buttons reflect cache state, show hashes/backends, badge recompute result, double-click triggers recomputeRequested, and right-click menu offers recompute (here/downstream)/inspector/copy-hash/repro command. Outcome_model has a dedicated inspector popover with stage/backend/determinism/hashes/last compute/result/repro string.
  • Selection drives scoping:
    • Genome/Edit/Perturbations → left builder visible; right sidebar -> Session/Guides.
    • Outcome/Evidence/Claims → center Analysis tab; right sidebar -> Compare.
  • Engine events: ingest marks genome computing/clean; HelixSpec runs mark outcome_model computing then clean (cache-hit tracked via RecomputeResult) and evidence dirty; evidence recompute rebuilds via run_to_evidence for the selected run_id, validates upstream outcome hash, and invalidates claims; claims recompute hashes evidence; snapshots mark evidence clean. Stale upstream → dropped (not failed) with reason.
  • Policy: RecomputePlanner encodes downstream rules once: outcome_model invalidates evidence+claims; evidence invalidates claims; claims invalidates nothing; failures short-circuit downstream.

Next Phases (aligned to north-star)

  • Phase 2: wire recomputeRequested(segment_id) to backend API (UI double-click already emits); surface cache hits via RecomputeResult; add richer inspector popover (hash, determinism policy, timing, repro command).
  • Phase 3: support branches (branch_id) for perturbation rails; selection provenance tags propagated to Lightcone/Outcome explorer.
  • Phase 4: export/import rail graph as provenance for repro bundles.

Validation Plan

  • Unit: hash stability + cache-state transitions (RailSegment, RailGraph.downstream, RailStateStore.mark_segment_state).
  • Qt UI: pytest-qt smoke to ensure rail spine renders buttons for all segments, selection toggles right-tab mapping, and computing/clean badges update on signal emission.
  • Integration: run HelixSpec demo and assert rail states transition DIRTY → COMPUTING → CLEAN; ingest path transitions genome state.
  • Visual: add EVS/Qt snapshot for rail spine badges (clean/dirty/computing) to catch regressions.