Implement XIC v2 control flow with IF, MATCH, LOOP operations

PHASE A: Safe predicate evaluator (glyphos/control/predicate.py) - AST-based safe expression evaluation - Supports comparisons, boolean ops, attribute access - Helper function: dominant_contains() - Protected against code injection attacks PHASE B: XICContext queue helpers - enqueue_chain(label) for FIFO chain scheduling - pop_next_chain() to get next scheduled chain - jump_to(label) for immediate destination changes PHASE C: Control flow operations (xic_ops.py) - op_IF: Conditional branching with optional else - op_MATCH: Pattern matching against fused fields - op_LOOP: Iterative execution with guardrails - Added to OP_TABLE for operation dispatch PHASE D: Execution loop enhancement (xic_vm.py) - Chain queue scheduling with label matching - Total steps tracking for guardrail enforcement - max_total_steps limit across all operations - Graceful execution stop on guardrail trigger PHASE E: Comprehensive test suite (tests/test_control_flow.py) - 14 unit tests covering all operations - Predicate evaluator tests - IF/MATCH/LOOP operation tests - Queue helper and guardrail tests - All tests passing (14/14) PHASE F: Example programs - demo_control_flow_if.gx.json: IF branching example - demo_control_flow_loop.gx.json: LOOP iteration example PHASE G: Complete documentation - XIC_V2_CONTROL_FLOW_SUMMARY.md: Technical guide - XIC_V2_QUICK_REFERENCE.md: Developer quick reference - FedMart UI and integration documentation Integration points: - FedMart telemetry captures control flow steps - UI dashboard displays control branching - Symbolic pipeline predicate evaluation - 100% backward compatible with XIC v1.5 Test results: 36/36 passing (14 control flow + 12 FedMart + 10 UI) Status: Production ready
2026-05-21 03:40:39 -04:00
parent 8f55949b11
commit c3a826b65c
17 changed files with 4299 additions and 3 deletions
@@ -0,0 +1,383 @@
+# FedMart UI - XIC Real-Time Pipeline Monitor
+
+Real-time telemetry dashboard for XIC (eXtended Infrastructure Cognition) symbolic pipeline execution with interactive guardrail controls and glyph resonance visualization.
+
+## Overview
+
+The FedMart UI provides a browser-based monitoring interface for the XIC v1.5 symbolic pipeline. It connects to the telemetry ingestion service via WebSocket to receive real-time updates about pipeline execution, multi-glyph resonance scores, and guardrail events.
+
+### Key Features
+
+- **Pipeline Timeline**: Step-by-step execution trace with timing information
+- **Glyph Resonance Heatmap**: Visual representation of resonance weights across glyphs using a color-coded canvas
+- **Glyph Inspector**: Detailed metrics for individual glyphs (weight, lineage score, contributor score, etc.)
+- **Guardrail Control**: Live guardrail status display with pause and throttle buttons
+- **Specification Coverage**: Track XIC instruction implementation status and test coverage
+- **Real-time Updates**: WebSocket-based live streaming of telemetry events
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  React/Browser (or Static HTML)                         │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  XIC Panel (index.html)                          │   │
+│  │  ├─ Timeline Visualization                      │   │
+│  │  ├─ Heatmap Canvas                              │   │
+│  │  ├─ Glyph Inspector                             │   │
+│  │  ├─ Guardrail Control                           │   │
+│  │  └─ Spec Coverage                               │   │
+│  └─────────────────────────────────────────────────┘   │
+│           ↓ WebSocket & REST                           │
+├─────────────────────────────────────────────────────────┤
+│  FastAPI Backend (server.py)                            │
+│  ├─ /ws/fedmart/xic (WebSocket broadcast)             │
+│  ├─ /fedmart/ingest/xic (Telemetry ingestion)         │
+│  ├─ /fedmart/control/pause (Pause signal)             │
+│  ├─ /fedmart/control/throttle (Throttle signal)       │
+│  └─ /fedmart/status (System status)                   │
+├─────────────────────────────────────────────────────────┤
+│  XIC Pipeline                                           │
+│  └─ Emits telemetry via FedMartAdapter                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Installation & Setup
+
+### Prerequisites
+
+- FastAPI server running (see `/home/dave/server.py`)
+- Python 3.9+ with uvicorn
+- Modern web browser with WebSocket support
+
+### Quick Start
+
+1. **Start the FastAPI server** (if not already running):
+   ```bash
+   python3 server.py
+   # Server starts on http://localhost:8000
+   ```
+
+2. **Open the UI in a browser**:
+   ```
+   http://localhost:8000/fedmart_ui/modules/xic_panel/
+   ```
+
+3. **Click "Connect to Feed"**:
+   - UI establishes WebSocket connection to `/ws/fedmart/xic`
+   - Status indicator changes to "Connected ✓"
+   - UI is ready to receive telemetry
+
+4. **Run an XIC pipeline**:
+   - Execute any XIC program that emits telemetry
+   - Telemetry events appear in real-time in the dashboard
+   - Timeline updates, heatmap renders, metrics display
+
+## Module Structure
+
+```
+fedmart_ui/
+├── README.md                    (this file)
+└── modules/
+    └── xic_panel/
+        ├── index.html           (UI template with all panels)
+        ├── xic_panel.css        (Professional dark-theme styling)
+        ├── xic_panel.js         (Real-time data handling & rendering)
+        └── README.md            (Detailed component documentation)
+```
+
+## File Descriptions
+
+### index.html
+
+HTML5 template with:
+- Responsive grid layout (2 columns on desktop, 1 on mobile)
+- Six main panels: header, timeline, heatmap, inspector, guardrail control, spec coverage
+- Canvas element for heatmap rendering
+- Dropdown for glyph selection
+- Buttons for feed connection and guardrail controls
+
+### xic_panel.css
+
+Stylesheet with:
+- Dark theme (#1e1e1e background, #667eea accent colors)
+- Responsive media queries for mobile compatibility
+- Color-coded elements:
+  - Blue: Standard pipeline steps
+  - Orange: Control/warning events
+  - Red: Guardrail triggers
+- Gradient heatmap legend (blue → green → orange)
+- Smooth transitions and hover effects
+
+### xic_panel.js
+
+JavaScript module (ES6) with:
+- `XICMonitor` class managing the entire UI state
+- WebSocket subscription with automatic reconnection
+- Telemetry processing and buffer management
+- Timeline rendering from step metadata
+- Canvas-based heatmap visualization with color gradients
+- Glyph selector population and inspector rendering
+- Guardrail alert display with action buttons
+- REST API calls to control endpoints
+
+## Telemetry Schema
+
+The dashboard expects telemetry in this format:
+
+```json
+{
+  "event_type": "symbolic_pipeline_run",
+  "timestamp": "2026-05-21T12:00:00Z",
+  "run_id": "xic_1234567890",
+  "program": "demo_symbolic.gx.json",
+  "chain_label": "analysis_1",
+  "glyph_ids": ["glyph://a", "glyph://b", "glyph://c"],
+  "glyph_count": 3,
+  "global_resonance_score": 0.847,
+  "steps_executed": 20,
+  "guardrails_triggered": [],
+  "resonance_map_summary": {
+    "top_glyphs": [
+      {"glyph_id": "glyph://a", "weight": 0.95},
+      {"glyph_id": "glyph://b", "weight": 0.73},
+      {"glyph_id": "glyph://c", "weight": 0.81}
+    ],
+    "average_resonance": 0.83
+  },
+  "raw_payload": {
+    "output_text": "Pipeline execution complete",
+    "fused_symbol_summary": { ... }
+  }
+}
+```
+
+**Required Fields:**
+- `event_type`: Always "symbolic_pipeline_run"
+- `timestamp`: ISO 8601 UTC timestamp
+- `run_id`: Unique identifier for the execution
+- `glyph_count`: Number of glyphs involved
+- `global_resonance_score`: 0.0-1.0 float
+- `steps_executed`: Integer count
+- `guardrails_triggered`: Array (empty if none)
+
+**Optional Fields:**
+- `program`, `chain_label`: Execution context metadata
+- `glyph_ids`, `resonance_map_summary`: Multi-glyph analysis
+- `raw_payload`: Raw pipeline output
+
+## UI Components
+
+### Pipeline Timeline
+Shows execution steps in chronological order:
+- Program loading
+- Chain entry
+- Multi-glyph resonance computation
+- Guardrail enforcement
+- Symbolic fusion
+
+Each step displays as a colored bar with the step name.
+
+### Glyph Resonance Heatmap
+Canvas-based visualization:
+- X-axis: Individual glyphs
+- Y-axis: Resonance weight (0.0-1.0)
+- Color: Blue (low) → Green (mid) → Orange (high)
+- Hover-friendly with clear labels
+
+### Glyph Inspector
+Detailed metrics for selected glyph:
+- Glyph ID
+- Resonance Weight (%)
+- Status (Active/Inactive)
+- (Extensible for additional metrics)
+
+### Guardrail Control
+- Live list of triggered guardrails
+- Pause Run button (sends control signal)
+- Throttle 50% button (reduces execution speed)
+- Enabled only when guardrails are active
+
+### Specification Coverage
+Status grid showing XIC instruction implementation:
+- Instructions grouped by phase
+- Color-coded by status: green (implemented), blue (validated), orange (pending)
+- Coverage percentage per instruction
+
+## REST API Endpoints
+
+### Telemetry Ingestion
+
+**POST /fedmart/ingest/xic**
+
+Ingest a telemetry event:
+```bash
+curl -X POST http://localhost:8000/fedmart/ingest/xic \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event_type": "symbolic_pipeline_run",
+    "glyph_count": 3,
+    "global_resonance_score": 0.847,
+    "steps_executed": 20,
+    "guardrails_triggered": []
+  }'
+```
+
+Response:
+```json
+{
+  "status": "accepted",
+  "run_id": "xic_1234567890",
+  "buffer_size": 42
+}
+```
+
+### Control Actions
+
+**POST /fedmart/control/pause**
+
+Send pause signal to a running pipeline:
+```bash
+curl -X POST http://localhost:8000/fedmart/control/pause \
+  -H "Content-Type: application/json" \
+  -d '{"run_id": "xic_1234567890"}'
+```
+
+**POST /fedmart/control/throttle**
+
+Throttle a pipeline's execution:
+```bash
+curl -X POST http://localhost:8000/fedmart/control/throttle \
+  -H "Content-Type: application/json" \
+  -d '{"run_id": "xic_1234567890", "factor": 0.5}'
+```
+
+### Telemetry Retrieval
+
+**GET /fedmart/telemetry/recent?limit=10**
+
+Retrieve recent telemetry events from buffer.
+
+### Status
+
+**GET /fedmart/status**
+
+System health and statistics.
+
+## WebSocket API
+
+### Connection
+
+```javascript
+const ws = new WebSocket('ws://localhost:8000/ws/fedmart/xic');
+```
+
+### Message Format
+
+Incoming telemetry (same as POST schema):
+```json
+{
+  "event_type": "symbolic_pipeline_run",
+  "timestamp": "2026-05-21T12:00:00Z",
+  ...
+}
+```
+
+## Color Scheme
+
+The dashboard uses a professional dark theme:
+
+| Element | Color | Use |
+|---------|-------|-----|
+| Background | #1e1e1e | Main surface |
+| Header | Gradient (#667eea → #764ba2) | Top bar |
+| Text | #e0e0e0 | Primary text |
+| Accent | #667eea | Highlights, borders |
+| Success | #4caf50 | Active status, implemented specs |
+| Warning | #ff9800 | Control events, pending specs |
+| Error | #f44336 | Guardrails, failures |
+| Heatmap Low | #0066cc | Blue (low resonance) |
+| Heatmap Mid | #00cc66 | Green (mid resonance) |
+| Heatmap High | #ff9900 | Orange (high resonance) |
+
+## Performance Considerations
+
+- **Buffer Size**: Limited to 1000 telemetry events (oldest discarded)
+- **WebSocket**: Efficient binary-free JSON transport
+- **Canvas Rendering**: Optimized for 600×200px heatmap
+- **Responsive Design**: CSS Grid adapts to viewport size
+- **Client-side State**: All rendering happens in the browser (no server-side session needed)
+
+## Troubleshooting
+
+### "Cannot connect to WebSocket"
+- Verify FastAPI server is running on port 8000
+- Check browser console for CORS/network errors
+- Ensure firewall allows WebSocket traffic (port 8000)
+
+### Heatmap not rendering
+- Browser must support HTML5 Canvas API
+- Check browser console for JavaScript errors
+- Verify telemetry includes `resonance_map_summary` with `top_glyphs`
+
+### No telemetry appearing
+- Click "Connect to Feed" first
+- Ensure XIC pipeline is emitting telemetry to `/fedmart/ingest/xic`
+- Check `/fedmart/telemetry/recent` endpoint to see if events are buffered
+- Monitor browser network tab (F12) for WebSocket messages
+
+### Slow performance with many events
+- Clear browser cache (Ctrl+Shift+Del)
+- Reduce WebSocket message frequency in source
+- Check browser memory usage (F12 Performance tab)
+
+## Testing
+
+Run the validation suite:
+
+```bash
+# Test FedMart adapter
+python3 tests/validate_fedmart_integration.py
+
+# Test UI components
+python3 tests/validate_ui_integration.py
+```
+
+All tests should show ✅ PASS status.
+
+## Future Enhancements
+
+- [ ] Export telemetry timeline as CSV
+- [ ] Real-time performance profiling graphs
+- [ ] Custom guardrail threshold configuration
+- [ ] Multi-run comparison view
+- [ ] Historical analysis dashboard
+- [ ] Integration with third-party monitoring (Grafana, Prometheus)
+
+## Architecture Notes
+
+The UI is deliberately **framework-agnostic**:
+- Pure HTML5 + CSS3 + ES6 JavaScript
+- No external dependencies (no npm, no build step)
+- Single 50KB JavaScript module
+- Easy to integrate into React, Vue, or standalone
+
+For a larger project, consider:
+- Wrapping `XICMonitor` as a React component
+- Using a state management library (Redux, Zustand)
+- Adding TypeScript for type safety
+- Building a D3.js visualization layer for complex graphs
+
+## Support
+
+For issues, questions, or feature requests:
+1. Check the troubleshooting section above
+2. Review telemetry schema in FedMart adapter (`integrations/fedmart/xic_adapter.py`)
+3. Check FastAPI server logs for backend errors
+4. Inspect browser console (F12) for frontend errors
+
+---
+
+**Status**: ✅ Production Ready  
+**Last Updated**: 2026-05-21  
+**Version**: 1.5.0