Orchestrator

.github/workflows/ci.yml

@@ -6,8 +6,44 @@ on:
       - main
   pull_request:
 
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
 jobs:
-  rust:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Run clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+  rust-test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -21,10 +57,37 @@ jobs:
       - name: Run Rust tests
         run: cargo test
 
+  rust-test-serde:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+
       - name: Run Rust serde tests
         run: cargo test --features serde
 
-  ui:
+  rust-doc:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build docs
+        run: cargo doc --no-deps --all-features
+
+  ui-build:
     runs-on: ubuntu-latest
     defaults:
       run:

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt --all -- --check
+        language: system
+        pass_filenames: false
+
+      - id: cargo-clippy
+        name: cargo clippy
+        entry: cargo clippy --all-targets --all-features -- -D warnings
+        language: system
+        pass_filenames: false
+
+      - id: cargo-test
+        name: cargo test
+        entry: cargo test
+        language: system
+        pass_filenames: false
+
+      - id: cargo-test-serde
+        name: cargo test --features serde
+        entry: cargo test --features serde
+        language: system
+        pass_filenames: false
+
+      - id: ui-build
+        name: ui build
+        entry: sh -c 'cd web/void-control-ux && npm run build'
+        language: system
+        pass_filenames: false

AGENTS.md

@@ -1,120 +1,168 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-This repository currently contains architecture and runtime-contract documentation for Void Control.
-
-- `spec/`: Canonical specifications (for example, `spec/void-control-runtime-spec-v0.1.md`).
-- `LICENSE`: Project license.
-
-When adding implementation code, keep the same separation of concerns defined in the spec:
-- Control-plane orchestration logic should be separate from runtime execution logic.
-- Add new specs to `spec/` and version them in the filename (for example, `*-v0.2.md`).
-
-## Build, Test, and Development Commands
-Use Cargo for local development and validation:
-
-- `cargo test`: Run core unit tests (no optional JSON compatibility feature).
-- `cargo test --features serde`: Run JSON compatibility tests and fixture-based checks.
-- `cargo test --features serde runtime::void_box::`: Run live-daemon client contract tests (mocked transport).
-- `VOID_BOX_BASE_URL=http://127.0.0.1:3000 cargo test --features serde --test void_box_contract -- --ignored --nocapture`: Run live daemon contract gate tests (tests auto-generate fallback specs under `/tmp`).
-- Optional spec overrides for policy behavior checks:
-  - `VOID_BOX_TIMEOUT_SPEC_FILE`
-  - `VOID_BOX_PARALLEL_SPEC_FILE`
-  - `VOID_BOX_RETRY_SPEC_FILE`
-  - `VOID_BOX_NO_POLICY_SPEC_FILE`
-- `cargo run --example normalize_void_box_run`: Run the typed normalization example.
-- `cargo run --bin normalize_fixture -- fixtures/sample.vbrun`: Normalize from local fixture format.
-
-### Void-Box Production Image (for UI/real Claude runs)
-
-When validating real pipeline execution from `void-control` UI, use the production
-void-box rootfs from the sibling repository:
+# AGENTS.md — void-control
+
+`void-control` is the control-plane side of the Void stack. It owns runtime
+contract normalization, orchestration planning, persistence, bridge APIs, and
+the operator UI. It does not implement VM isolation or guest execution; that
+belongs to `void-box`.
+
+## System boundary
+
+- `void-control`:
+  - normalizes `void-box` daemon responses into a stable contract
+  - plans and tracks multi-candidate executions
+  - persists execution state, events, candidate records, and message-box data
+  - exposes bridge APIs for launch, dry-run, and policy operations
+  - provides the graph-first web UI
+- `void-box`:
+  - launches isolated runtime execution
+  - produces run, event, stage, and artifact data
+  - enforces sandbox/runtime behavior
+
+When changing code here, preserve that boundary. Control-plane orchestration and
+runtime transport concerns should stay separate.
+
+## Repository layout
+
+- `spec/`: canonical specifications and design contracts
+- `src/contract/`: runtime contract types, normalization, and compatibility logic
+- `src/runtime/`: runtime adapter implementations (`MockRuntime`, `VoidBoxRuntimeClient`)
+- `src/orchestration/`: planning, persistence, scheduling, reduction, strategies
+- `src/bridge.rs`: HTTP bridge for launch, dry-run, execution inspection, and policy patching
+- `src/bin/voidctl.rs`: CLI entrypoint and bridge server
+- `tests/`: orchestration, bridge, runtime, and compatibility coverage
+- `web/void-control-ux/`: React/Vite operator dashboard
+- `docs/`: architecture notes, release process, and internal plans/specs
+
+## Module map
+
+### Rust library
+
+- `src/contract/`
+  - contract-facing API and normalization layer
+  - converts raw `void-box` payloads into stable `void-control` views
+- `src/runtime/`
+  - execution runtime abstraction plus mock and live `void-box` client
+  - provider launch injection for message-box inbox delivery
+- `src/orchestration/spec.rs`
+  - execution spec parsing and validation
+- `src/orchestration/variation.rs`
+  - candidate-generation sources such as `parameter_space`, `explicit`,
+    `leader_directed`, and `signal_reactive`
+- `src/orchestration/strategy.rs`
+  - swarm/search planning and reduction logic
+- `src/orchestration/message_box.rs`
+  - communication intent routing, inbox snapshots, and `MessageStats` extraction
+- `src/orchestration/store/`
+  - persisted execution, event, candidate, and message-box data
+- `src/orchestration/service.rs`
+  - orchestration coordinator; plans, dispatches, reduces, and persists
+- `src/orchestration/scheduler.rs`
+  - global execution/candidate dispatch ordering
+- `src/orchestration/reconcile.rs`
+  - restart/reload of persisted active work
+- `src/bridge.rs`
+  - serde-gated HTTP routes for UI/bridge workflows
+
+### Web UI
+
+- `web/void-control-ux/`
+  - graph-first operator dashboard
+  - reads daemon and bridge APIs
+  - build is the current validation gate for frontend changes
+
+## Core local commands
+
+Rust validation:
 
 ```bash
-cd /home/diego/github/agent-infra/void-box
-TMPDIR=$PWD/target/tmp scripts/build_claude_rootfs.sh
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test
+cargo test --features serde
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
 ```
 
-Start daemon with production kernel/initramfs:
+UI validation:
 
 ```bash
-cd /home/diego/github/agent-infra/void-box
-export ANTHROPIC_API_KEY=sk-ant-...
-export VOID_BOX_KERNEL=/boot/vmlinuz-$(uname -r)
-export VOID_BOX_INITRAMFS=$PWD/target/void-box-rootfs.cpio.gz
-cargo run --bin voidbox -- serve --listen 127.0.0.1:43100
+cd web/void-control-ux
+npm ci
+npm run build
 ```
 
-Start bridge (required for Launch modal spec upload/content mode):
+Bridge and UI local run:
 
 ```bash
-cd /home/diego/github/void-control
 cargo run --features serde --bin voidctl -- serve
+cd web/void-control-ux
+npm run dev -- --host 127.0.0.1 --port 3000
 ```
 
-Start UI:
+## Runtime compatibility commands
+
+Live daemon contract gate:
 
 ```bash
-cd /home/diego/github/void-control/web/void-control-ux
-npm run dev -- --host 127.0.0.1 --port 3000
+VOID_BOX_BASE_URL=http://127.0.0.1:43100 \
+cargo test --features serde --test void_box_contract -- --ignored --nocapture
 ```
 
-Important:
-- Do not use `/tmp/void-box-test-rootfs.cpio.gz` for production/runtime UI validation.
-- `target/void-box-rootfs.cpio.gz` is the expected production image path.
+Optional policy fixture overrides:
 
-### UI Debugging Requirement
+- `VOID_BOX_TIMEOUT_SPEC_FILE`
+- `VOID_BOX_PARALLEL_SPEC_FILE`
+- `VOID_BOX_RETRY_SPEC_FILE`
+- `VOID_BOX_NO_POLICY_SPEC_FILE`
 
-For UI work in `web/void-control-ux`, browser automation/inspection is required.
-Do not rely on screenshot-only iteration when layout, DOM state, resize behavior,
-or graph rendering need verification.
+## UI workflow expectations
+
+For UI work in `web/void-control-ux`, use browser automation/inspection for DOM,
+layout, resize, console, and network validation. Screenshots are fallback only.
 
 Preferred order:
 
-- Use configured browser MCP first.
-- If browser MCP is unavailable, install and use Playwright locally.
-- Screenshots are a fallback only, not the primary workflow.
+- configured browser MCP
+- local Playwright if browser MCP is unavailable
+- screenshots only when interactive inspection is impossible
 
-Current local browser MCP:
+## Documentation expectations
 
-- `chrome-devtools` is already configured in `~/.codex/config.toml`.
-- This should be the default tool for DOM inspection, layout debugging, console
-  errors, network checks, and viewport validation.
+- add new specs under `spec/` with versioned filenames
+- keep implementation-facing architecture notes in `docs/`
+- update `README.md`, `AGENTS.md`, or `docs/architecture.md` when behavior or
+  workflows change materially
 
-Playwright install fallback:
+## Testing expectations
 
-```bash
-cd /home/diego/github/void-control/web/void-control-ux
-npm install -D playwright
-npx playwright install chromium
-```
+- keep unit/contract tests close to the relevant Rust logic where practical
+- use integration tests in `tests/` for orchestration, bridge, and acceptance flows
+- before merging Rust changes, run:
+  - `cargo fmt --all -- --check`
+  - `cargo clippy --all-targets --all-features -- -D warnings`
+  - `cargo test`
+  - `cargo test --features serde`
+- before merging UI changes, also run:
+  - `npm run build` in `web/void-control-ux`
 
-If Playwright MCP is later added, prefer that over manual screenshots for UI
-inspection. No dedicated local skill currently exists in this repo for
-Playwright setup; use browser MCP or direct Playwright commands.
+## Pre-commit
 
-## Coding Style & Naming Conventions
-For documentation and future code contributions:
+This repo uses a checked-in `.pre-commit-config.yaml` for local validation.
 
-- Use clear, boundary-focused naming aligned with the spec (`Run`, `Stage`, `Attempt`, `Runtime`, `Controller`).
-- Keep Markdown headings hierarchical and concise.
-- Prefer short sections and bullet lists over long prose blocks.
-- Use ASCII unless a symbol is required for technical clarity.
+Typical setup:
 
-## Testing Guidelines
-- Keep contract tests in module `#[cfg(test)]` blocks close to conversion/runtime logic.
-- Add fixture-based tests for compatibility behavior under `--features serde`.
-- Validate both paths before PRs:
-  - `cargo test`
-  - `cargo test --features serde`
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run --all-files
+```
 
-## Commit & Pull Request Guidelines
-Git history is minimal (`Initial commit`), so adopt a consistent imperative style now:
+## Commit and PR guidance
 
-- Commit format: `area: concise action` (example: `spec: clarify cancellation semantics`).
-- Keep commits focused to one concern.
+- commit format: `area: concise action`
+- keep commits scoped to one concern
 - PRs should include:
-  - A short problem statement.
-  - A summary of what changed.
-  - Any spec sections affected (file paths + headings).
-  - Follow-up work, if intentionally deferred.
+  - problem statement
+  - summary of changes
+  - affected specs/docs
+  - verification commands run
+  - follow-up work, if intentionally deferred