# BEIST Roadmap: From Event System to Workflow Language

## Vision

BEIST is evolving from a simple event-driven resource system into a complete workflow orchestration language. The key insight: **everything can be expressed through events and resources**, including complex workflows with branching, parallelism, and error handling.

## Current State ✅

- **Event-driven resource system** - Everything is a resource responding to events
- **File watching without daemons** - Resources manage their own processes
- **Event graph visualization** - See cascades with `graph` command
- **Dynamic monitoring** - Subscribe to event patterns in REPL
- **Complete isolation** - Resources manage their own state

## Phase 1: Sequential Chains (Next Sprint)

Simple dependency chains in the REPL:

```bash
BEIST> chain gpu:compile -> zig:compile -> deploy
```

Compiles to ephemeral chain resource that emits events in sequence.

**Implementation:** ~50 lines in REPL

## Phase 2: Conditional Branching

Add if-then-else logic:

```lisp
BEIST> chain (if (tests:pass) 
                 (deploy:prod)
                 (rollback))
```

Resources check conditions and branch event flow.

**Implementation:** ~100 lines for parser + compiler

## Phase 3: Parallel Execution

Fork-join patterns for concurrent work:

```lisp
BEIST> chain (parallel 
               (gpu:compile)
               (cpu:compile)
               (tests:run))
             (join zig:link)
```

Uses event counting to synchronize.

**Implementation:** ~50 lines for parallel coordinator

## Phase 4: Full S-Expression Language

Complete workflow DSL:

```lisp
BEIST> chain 
  (let [env (get-env "BUILD_MODE")]
    (cond
      [(= env "prod") (deploy:production)]
      [(= env "staging") (deploy:staging)]
      [else (tests:local)]))
```

Features:
- Variables and bindings
- Pattern matching
- Loops (foreach, while)
- Error handling (try-catch)

**Implementation:** ~500 lines for full language

## Phase 5: Visual Pipeline Builder

Interactive TUI/Web UI for building chains:

```
┌─ Build Pipeline ────────────────┐
│                                  │
│  [gpu:compile] ──┐               │
│                  ├──> [zig:link] │
│  [cpu:compile] ──┘               │
│                                  │
│  + Add Stage   ⚙ Configure       │
└──────────────────────────────────┘
```

**Implementation:** Separate tool using BEIST API

## Phase 6: Roundtrip Tooling

Import/Export capabilities:

```bash
# Import from other tools
BEIST> import github-action .github/workflows/ci.yml
BEIST> import makefile Makefile

# Export to other formats
BEIST> export chain:ci --format=github-action
BEIST> export chain:build --format=dockerfile
```

**Implementation:** Format converters for popular tools

## Phase 7: Distributed Execution

Run resources across machines:

```json
{
  "type": "gpu-compiler",
  "remote": "gpu-server.local",
  "ssh-key": "~/.ssh/beist"
}
```

Events flow across network boundaries.

**Implementation:** TCP event bridge + SSH resource execution

## Design Principles

1. **No new concepts in core** - Everything builds on events and resources
2. **Progressive complexity** - Simple things simple, complex things possible  
3. **Textual first** - GUI/visual tools are layers on top
4. **Event transparency** - Always be able to see what's happening
5. **Resource isolation** - No global state or coupling

## Contributing

Each phase is designed to be independently valuable. Pick a phase and help build it!

### Phase 1 Needs:
- [ ] Basic chain parser
- [ ] Dynamic resource creation
- [ ] Tests for chain execution

### Phase 2 Needs:
- [ ] S-expression tokenizer
- [ ] Conditional resource compiler
- [ ] Branch testing framework

## Timeline

- **Phase 1**: 1-2 days (minimal chain support)
- **Phase 2**: 1 week (branching)
- **Phase 3**: 3 days (parallelism)
- **Phase 4**: 2-3 weeks (full language)
- **Phase 5**: 1 month (visual builder)
- **Phase 6**: 2 weeks per format (import/export)
- **Phase 7**: 1 month (distributed)

## Success Metrics

We'll know we've succeeded when:

1. Complex CI/CD pipelines can be expressed in a few lines
2. Users can compose workflows without writing .beist files
3. The system can replace Make, GitHub Actions, and similar tools
4. Workflows are debuggable through event inspection
5. Anyone can understand a workflow by reading the S-expressions

## Get Involved

Start with Phase 1 - just make chains work with `->` syntax. Everything else builds from there!

```bash
git clone https://github.com/[org]/beist-core
cd beist-core
npm install
npm run build
./dist/cli/index.js repl

BEIST> chain echo:hello -> echo:world -> echo:done
```

The future is event-driven! 🚀