Overview
The pvm-compiler operates as an L4 Domain Authority within the Prismatic Platform's compilation domain, providing high-performance compilation of intermediate representation (IR) workflows into optimized PVM bytecode for execution on the Prismatic Virtual Machine. This agent transforms declarative workflow specifications -- agent orchestration plans, pipeline definitions, and multi-step operational sequences -- into efficient executable representations that the pvm-executor can dispatch with minimal runtime overhead. The compiler applies multi-level optimization passes that eliminate redundant operations, reorder instructions for optimal resource utilization, and generate specialized code paths for common execution patterns.
The PVM compiler serves a critical role in the platform's performance architecture: the quality of compiled bytecode directly affects the execution speed of every agent workflow, quality gate evaluation, and pipeline operation. Built on the BEAM virtual machine using OTP process isolation, the compiler runs as a dedicated GenServer process that accepts compilation requests, applies the optimization pipeline, and produces verified bytecode artifacts. Compiled artifacts are cached in ETS tables with invalidation triggered by source workflow modifications, achieving sub-millisecond dispatch for previously compiled workflows while maintaining correctness guarantees through cache coherence protocols.
Compilation Pipeline Architecture
The compiler implements a multi-phase compilation pipeline that progressively transforms high-level workflow specifications into optimized executable bytecode.
Phase 1: Parsing and Validation ingests workflow specifications in the platform's declarative format and validates them against the PVM instruction set specification. Syntactic validation ensures structural correctness, while semantic validation verifies that all referenced agents, capabilities, and resources exist in the AIAD registry. Invalid workflows are rejected with precise error diagnostics identifying the specific validation failure.
Phase 2: IR Generation translates validated workflow specifications into the compiler's intermediate representation -- a directed acyclic graph (DAG) of typed operations connected by data flow edges. Each IR node represents a single computational step (agent invocation, data transformation, conditional branch, resource acquisition) annotated with type information, resource requirements, and estimated execution cost. The IR serves as the common representation for all subsequent optimization passes.
Phase 3: Optimization applies a configurable sequence of optimization passes to the IR graph. Each pass transforms the graph to improve execution efficiency while preserving semantic equivalence with the original specification. The optimization pipeline is itself configurable, with different optimization levels for development (minimal optimization, fast compilation) and production (aggressive optimization, slower compilation).
Phase 4: Code Generation translates the optimized IR into PVM bytecode -- the binary instruction format executed by the PVM executor. Code generation produces compact bytecode with embedded metadata for debugging, profiling, and hot code reload support.
Phase 5: Verification validates the compiled bytecode against the original specification through symbolic execution, confirming that the compiled code produces identical outputs for all valid inputs. This final verification step catches any correctness bugs introduced by optimization passes.
Optimization Passes
The compiler implements multiple optimization passes, each targeting a specific class of inefficiency in workflow specifications.
Dead Code Elimination identifies and removes operations whose results are never consumed by downstream steps. Workflow specifications often include diagnostic or conditional branches that are unreachable under current configuration, and eliminating these reduces both bytecode size and execution time.
Common Subexpression Elimination detects operations that compute identical results (same operation, same inputs) and merges them into a single computation with shared results. This commonly arises when multiple workflow branches require the same data preparation step.
Operation Reordering rearranges the execution order of independent operations to maximize parallelism and minimize resource contention. Operations without data dependencies can execute concurrently, and the compiler identifies the optimal execution order that maximizes concurrent execution while respecting resource constraints.
Constant Folding evaluates operations with statically known inputs at compile time, replacing them with their computed results. Configuration-dependent branches that can be resolved at compilation are eliminated, producing specialized bytecode for the current configuration.
Inline Expansion replaces calls to small, frequently-used sub-workflows with their bytecode bodies, eliminating call overhead. The compiler applies inlining selectively based on call frequency and sub-workflow size, using cost-benefit analysis to determine when inlining improves overall performance.
Resource Coalescing identifies operations that acquire and release the same resource type in sequence and combines their resource allocations into a single acquisition-release pair, reducing resource management overhead.
Bytecode Format
The PVM bytecode format is a compact binary representation designed for efficient interpretation by the PVM executor. Each bytecode instruction consists of an opcode (identifying the operation type), operand specifications (identifying data sources and destinations), and metadata annotations (providing debugging information and execution hints).
The format supports variable-length instructions to minimize bytecode size for common operations. High-frequency operations (data access, simple transformations) use single-byte opcodes, while complex operations (agent invocations, resource acquisitions) use multi-byte opcodes with extended operand specifications.
Bytecode artifacts include embedded symbol tables mapping instruction addresses to source workflow locations, enabling precise error reporting and execution tracing without separate debug information files.
Cache Architecture
Compiled bytecode is cached in ETS tables indexed by workflow specification hash, enabling sub-millisecond lookup for previously compiled workflows. The cache implements a coherence protocol that invalidates entries when source specifications change, agent capabilities are modified, or platform configuration affects compilation output.
Cache warming runs during platform startup, pre-compiling frequently-used workflows to eliminate first-execution compilation latency. The cache also supports incremental compilation: when a workflow specification changes, only the affected IR subgraph is recompiled and merged with the cached bytecode for unchanged portions.
Command Interface
| Command | Description | Authority |
|---|---|---|
/pvm compile | Compile a workflow specification into PVM bytecode | L4+ |
/pvm optimize | Recompile with specified optimization level | L4+ |
/pvm cache-status | Display bytecode cache statistics and hit rates | L4+ |
/pvm disassemble | Display human-readable bytecode for a compiled workflow | L4+ |
Coordination
| Agent | Relationship |
|---|---|
| pvm-executor | Consumes compiled bytecode for workflow execution |
| pvm-adaptive-scheduler | Compilation task scheduling and resource allocation |
| pvm-tracer | Provides execution profiling data for optimization guidance |
| quality-gates-specialist | Compilation quality verification within quality gate pipeline |
Integration Architecture
| Component | Relationship |
|---|---|
| Prismatic Agents | Runtime execution and lifecycle management |
| Prismatic Telemetry | Compilation performance metrics and cache statistics |
| AIAD Registry | Agent capability lookup for compilation validation |
| ETS Cache | Compiled bytecode storage with coherence management |
| SEADF Pipeline | Evolution workflow compilation and optimization |
Enforcement
Compilation operations comply with the NO MERCY doctrine -- bytecode that fails verification against the source specification is rejected, and optimization passes that introduce correctness bugs are immediately disabled and flagged for investigation. The NO DOUBTS principle requires that every compiled artifact includes verification evidence demonstrating semantic equivalence with its source specification. The Trinity Gate validates compilation outputs through structural consistency (bytecode instruction sequence is well-formed), logical consistency (data flow types match across instruction boundaries), and formal necessity (compiled behavior matches specification for all valid inputs).
Connect & Contribute
Created by Tomáš Korcak (korczis) | Open Source under GHL