hristudio/docs/experiment-designer-redesign.md

Experiment Designer Redesign (Production Baseline)

This document defines the production-ready redesign of the Experiment Designer. It supersedes prior "modular refactor" notes and consolidates architecture, hashing, drift detection, UI/UX, state management, validation, plugin integration, saving/versioning, and export strategy. All implementation must adhere to this specification to ensure reproducibility, extensibility, and maintainability.

---

1. Goals

• Provide a clear, fast, and intuitive hierarchical design workflow.
• Guarantee reproducibility via deterministic hashing and provenance retention.
• Surface plugin dependency health and schema drift early.
• Support scalable experiments (many steps/actions) without UI degradation.
• Enable structured validation (structural, parameter-level, semantic) before compilation.
• Provide robust export/import and future multi-user collaboration readiness.
• Maintain 100% type safety and consistent design patterns across the platform.

---

2. Conceptual Model

Hierarchy:

Experiment
  └─ Step (ordered, typed)
        └─ Action (ordered, typed, provenance-bound)

Key invariants:

• Step order is zero-based, contiguous after any mutation.
• Action orderIndex is zero-based within its parent step.
• Each action retains provenance: { source.kind, pluginId?, pluginVersion?, baseActionId? }
• Execution descriptors are retained for reproducibility (transport, ros2, rest, retryable, timeoutMs).

---

3. Hashing & Integrity Guarantees

3.1 Purposes of Hashing

• Detect structural drift between persisted design and working edits.
• Bind design to plugin and action schemas for reproducibility.
• Support execution graph provenance (hash at compile time).
• Enable export integrity and offline verification.

3.2 Design Hash Components

Included:

• Steps (ordered): id, name, type, order, trigger.type, sorted trigger condition keys.
• Actions (per step, ordered): id, type, source.kind, pluginId, pluginVersion, baseActionId, execution.transport, parameter key set (NOT values by default—configurable).
• Optional: parameter values (toggle design mode if needed—default: exclude values to reduce false-positive drift).

Excluded:

• Ephemeral UI state (expanded, selection state).
• Human-friendly timestamps or transient meta.

3.3 Canonicalization Steps

1. Deep clone design subset.
2. Remove undefined keys.
3. Sort object keys recursively.
4. Sort arrays where semantic ordering is not meaningful (e.g. condition key sets).
5. JSON stringify (no whitespace).
6. SHA-256 digest → hex.

3.4 Incremental Hash Optimization

Per-action hash → per-step hash → design hash:

H_action = hash(canonical(actionMeta))
H_step = hash(stepMeta + concat(H_action_i))
H_design = hash(globalMeta + concat(H_step_i))

Recompute only modified branches for responsiveness.

3.5 Drift States

State	Condition
Unvalidated	No validation performed since load
Validated	Last validated hash matches stored experiment integrity hash and working snapshot unchanged
Drift	(A) Working snapshot changed since last validation OR (B) validated hash ≠ stored integrity hash
Plugin Drift	Design validated, but one or more action definitions (schema/provenance) no longer match registry

3.6 Plugin Signature Drift

Signature hash per action definition: hash of (type + category + parameterSchema + transport + baseActionId + pluginVersion).

• If signature mismatch for existing action instance: mark as “schema drift”.
• Provide reconciliation CTA to refetch schema and optionally run migration.

---

4. UI Architecture

High-level layout:

┌───────────────────────────────────────────────────────────────────────────┐
│ Header: breadcrumbs • experiment name • hash badge • plugin deps summary  │
├──────────────┬───────────────────────────────┬────────────────────────────┤
│ Action       │ Step Flow (sortable linear)   │ Properties / Inspector      │
│ Library      │ - Step cards (collapsible)     │ - Step editor               │
│ - Search     │ - Inline action list           │ - Action parameters         │
│ - Categories │ - DnD (steps/actions/library)  │ - Validation & drift panel  │
│ - Plugins    │ - Structural markers           │ - Dependencies & provenance │
├──────────────┴───────────────────────────────┴────────────────────────────┤
│ Bottom Save Bar: dirty state • versioning • export • last saved • conflicts│
└───────────────────────────────────────────────────────────────────────────┘

Component responsibilities:

Component	Responsibility
DesignerShell	Data loading, permission guard, store boot
ActionLibraryPanel	Search/filter, categorized draggable items
StepFlow	Rendering + reordering steps & actions
StepCard	Step context container
ActionItem	Visual + selectable action row
PropertiesPanel	Context editing (step/action)
ParameterFieldFactory	Schema → control mapping
ValidationPanel	Issue listing + filtering
DependencyInspector	Plugin + action provenance health
SaveBar	Hash/drift/dirtiness/export/version controls
hashing.ts	Canonicalization + incremental hashing
validators.ts	Rule execution (structural, parameter)
exporters.ts	Export bundle builder
store/useDesignerStore.ts	Central state store

---

5. State Management

Use a lightweight, framework-agnostic, fully typed store (Zustand). Core fields:

{
  steps: ExperimentStep[]
  dirty: Set<string>
  selectedStepId?: string
  selectedActionId?: string
  lastPersistedHash?: string
  lastValidatedHash?: string
  lastValidatedSnapshot?: string
  pluginSignatureIndex: Record<actionTypeOrId, string>
  validationIssues: Record<entityId, string[]>
  pendingSave?: boolean
  conflict?: { serverHash: string; localHash: string }
}

Actions

• setSteps, upsertStep, removeStep, reorderStep
• upsertAction, removeAction, reorderAction
• markDirty(entityId)
• computeDesignHash()
• setValidationResult({ hash, issues, snapshot })
• applyServerSync({ steps, hash })
• recordConflict(serverHash, localHash)

---

6. Drag & Drop

Library → Step

• Drag action definition placeholder onto step drop zone triggers action instantiation. Step reorder
• Sortable vertical list with keyboard accessibility. Action reorder
• Sortable within a step (no cross-step move initially; future extension). Framework: @dnd-kit/core + @dnd-kit/sortable.

Accessibility:

• Custom keyboard handlers: Up/Down to move selection; Alt+Up/Down to reorder.

---

7. Parameters & Control Mapping

Mapping:

Schema Type	Control
boolean	Switch
number (bounded)	Slider + numeric display
number (unbounded)	Numeric input
text short	Text input
text long	Textarea (expandable)
select/enumeration	Select / Combobox
multi-select	Tag list (future)
json/object	Lazy code editor (future)

Enhancements:

• Show required indicator
• Inline validation message
• Revert-to-default button if default provided
• Modified badge (dot) for overridden parameters

---

8. Validation System

Levels:

1. Structural
   • No empty step names
   • Steps must have valid type
   • Conditional/loop must define required condition semantics
2. Parameter
   • Required values present
   • Number bounds enforced
   • Enum membership
3. Semantic
   • No unresolved plugin dependency
   • Unique action IDs and step IDs
   • Loop guard presence (future)
4. Execution Preflight (optional)
   • Detect obviously irrecoverable execution (e.g. empty parallel block)

Severity classification:

• Error: blocks save/compile
• Warning: surfaced but non-blocking
• Info: advisory (e.g. unused parameter)

Store format:

validationIssues: {
  [entityId: string]: { severity: "error" | "warning" | "info"; message: string }[]
}

Rendering:

• Badge on step/actions with count + highest severity color.
• Panel filter toggles (Errors / Warnings / All).
• Inline icon markers.

---

9. Plugin Integration & Drift

Definitions loaded into ActionRegistry:

{
  id,
  type,
  name,
  category,
  parameters[],
  source: { kind, pluginId?, pluginVersion?, baseActionId? },
  execution?,
  parameterSchemaRaw
}

Per-definition signatureHash computed: hash(type + category + JSON(parameterSchemaRaw) + execution.transport + baseActionId + pluginVersion)

Per-action drift logic:

• If action.source.pluginVersion missing in registry → Blocked (hard drift).
• If signatureHash mismatch → Soft drift (allow edit, prompt reconcile).
• Provide “Reconcile” overlay listing changed parameters (added / removed / type changed).

---

10. Saving & Versioning

Save triggers:

• Manual (primary save button or Cmd+S)
• Debounced auto-save (idle > 5s, no pending errors)
• Forced save before export

Payload:

{
  id,
  visualDesign: { steps, version, lastSaved },
  createSteps: true,
  compileExecution: true
}

Version management:

• If structural change (add/remove/reorder step/action or change type) → version bump (auto unless user disables).
• Parameter-only changes may optionally not bump version (configurable toggle; default: no bump).
• UI: dropdown / toggle “Increment version on save”.

Conflict detection:

• Server returns persisted integrityHash.
• If local lastPersistedHash differs and serverHash differs from our pre-save computed hash → conflict modal.
• Provide:
  • View diff summary (step added/removed, action count deltas).
  • Override server (if authorized) or Reload.

---

11. Export / Import

Export bundle structure:

{
  "format": "hristudio.design.v1",
  "exportedAt": "...ISO8601...",
  "experiment": {
    "id": "...",
    "name": "...",
    "version": 4,
    "integrityHash": "...",
    "steps": [... canonical steps ...],
    "pluginDependencies": ["pluginA@1.2.1", "robot.voice@0.9.3"]
  },
  "compiled": {
    "graphHash": "...",
    "steps": 12,
    "actions": 47,
    "plan": { /* normalized execution nodes */ }
  }
}

Import validation:

• Check format signature & version.
• Recompute design hash vs embedded.
• Check plugin availability (list missing).
• Offer “Install required plugins” if privileges allow.

---

12. Accessibility & UX Standards

• Keyboard traversal (Tab / Arrow) across steps & actions.
• Focus ring on selected entities.
• ARIA labels on all interactive controls (drag handles, add buttons).
• Color usage passes contrast (WCAG 2.1 AA).
• Non-color indicators for drift (icons / labels).
• All icons: Lucide only.

---

13. Performance Considerations

• Virtualize StepFlow when step count > threshold (e.g. 50).
• Memoize parameter forms (avoid re-render on unrelated step changes).
• Incremental hashing—avoid full recompute on each keystroke.
• Lazy-load advanced components (JSON editor, large schema viewers).

---

14. Testing Strategy

Unit Tests:

• Hash determinism (same structure -> same hash).
• Hash sensitivity (reorder step / change action type -> different hash).
• Signature drift detection logic.
• Validation rule coverage (structural & parameter).

Integration Tests:

• Save cycle (design → save → fetch → hash equality).
• Plugin dependency missing scenario.
• Conflict resolution workflow.

Edge Cases:

• Empty experiment (0 steps) → validation error.
• Conditional step with no conditions → error.
• Loop step missing guard → warning (future escalation).
• Plugin removed post-design → plugin drift surfaced.

---

15. Migration Plan (Internal)

1. Introduce new store + hashing modules.
2. Replace current BlockDesigner usage with DesignerShell.
3. Port ActionLibrary / StepFlow / PropertiesPanel to new contract.
4. Add SaveBar + drift/UI overlays.
5. Remove deprecated legacy design references (no “enhanced” terminology).
6. Update docs cross-links (project-overview.md, implementation-details.md).
7. Add export/import UI.
8. Stabilize, then enforce hash validation before trial creation.

---

16. Security & Integrity

• Server must recompute its own structural hash during compile to trust design.
• Client-submitted integrityHash considered advisory; never trusted alone.
• Plugin versions pinned explicitly inside actions (no implicit latest resolution).
• Attempting to execute an experiment with unresolved drift prompts required validation.

---

17. Future Extensions

Feature	Description
Real-time co-editing	WebSocket presence + granular patch sync
Branching workflows	Conditional branches forming DAG (graph mode)
Step templates library	Shareable reproducible step/action sets
Parameter presets	Save named parameter bundles per action type
Timeline estimation view	Aggregate predicted duration
Replay / provenance diff	Compare two design versions side-by-side
Plugin action migration	Scripted param transforms on schema changes
Execution simulation	Dry-run graph traversal with timing estimates

---

18. Implementation Checklist (Actionable)

• hashing.ts (canonical + incremental)
• validators.ts (structural + param rules)
• store/useDesignerStore.ts
• ActionRegistry rewrite with signature hashing
• ActionLibraryPanel (search, categories, drift indicators)
• StepFlow + StepCard + ActionItem (DnD with @dnd-kit)
• PropertiesPanel + ParameterFieldFactory
• ValidationPanel + badges
• DependencyInspector + plugin drift mapping
• SaveBar (dirty, versioning, export)
• Exporter (JSON bundle) + import hook
• Conflict modal
• Drift reconciliation UI
• Unit & integration tests
• Docs cross-link updates
• Remove obsolete legacy code paths

(Track progress in docs/work_in_progress.md under “Experiment Designer Redesign Implementation”.)

---

19. Cross-References

• See docs/implementation-details.md (update with hashing + drift model)
• See docs/api-routes.md (experiments.update, experiments.validateDesign)
• See docs/database-schema.md (steps, actions, provenance fields)
• See docs/project-overview.md (designer feature summary)
• See docs/work_in_progress.md (status tracking)

---

20. Summary

This redesign formalizes a production-grade, reproducible, and extensible experiment design environment with deterministic hashing, plugin-aware action provenance, structured validation, export integrity, and a modular, performance-conscious UI framework. Implementation should now proceed directly against this spec; deviations require documentation updates and justification.

---

End of specification.