Runtime Engine

FAI Engine

The runtime that reads fai-manifest.json, resolves context, wires primitives, runs hooks, and evaluates quality — 7 modules, 42 tests, 12ms.

FAI Primitives

What does the FAI Engine do?

The FAI Protocol defines how primitives connect. The FAI Engine executes that specification. Give it a fai-manifest.json and it will:

Read & Validate

Parse the manifest, validate every field against JSON schemas, reject invalid configs early

Resolve & Wire

Load FROOT knowledge modules, resolve WAF pillars, discover primitives, inject shared context

Guard & Evaluate

Activate quality gates, run hooks on lifecycle events, evaluate every response against thresholds

Interactive Pipeline

fai-manifest.json — Play 01: Enterprise RAG

{
  "play": "01-enterprise-rag",
  "version": "1.0.0",
  "context": {
    "knowledge": [
      "R2-RAG-Architecture",
      "O3-MCP-Tools",
      "T3-Production-Patterns",
      "F1-GenAI-Foundations"
    ],
    "waf": [
      "security",
      "reliability",
      "cost-optimization",
      "operational-excellence",
      "responsible-ai"
    ],
    "scope": "enterprise-rag-qa"
  },
  "primitives": {
    "agents": 3,
    "instructions": 3,
    "skills": 1,
    "hooks": 3,
    "guardrails": {
      "groundedness": 0.95,
      "coherence": 0.9,
      "relevance": 0.85,
      "safety": 0,
      "costPerQuery": 0.01
    }
  },
  "infrastructure": {
    "bicep": "./infra/main.bicep"
  },
  "toolkit": {
    "devkit": ".github/",
    "tunekit": "config/",
    "speckit": "spec/"
  }
}

Load Manifest

Read fai-manifest.json, validate against fai-manifest.schema.json

2ms

Resolve Context

Load 4 FROOT knowledge modules + 5 WAF pillar definitions + scope

4ms

Wire Primitives

Discover and validate 3 agents + 3 instructions + 1 skill + 3 hooks

3ms

Apply Guardrails

Activate quality gates: groundedness≥0.95, coherence≥0.90, safety=0

1ms

Engine Ready

All primitives wired, context shared, guardrails enforced, hooks armed

2ms

7 Engine Modules

Each module is a focused unit with a single responsibility. Together they form the full FAI Engine pipeline.

Pipeline Flow

The engine processes a manifest through 6 sequential stages — each building on the previous.

Load Manifest

Resolve Context

Wire Primitives

Run Hooks

Evaluate

Bridge to MCP

Usage

Use the engine programmatically or from the command line.

Node.js — Programmatic Usage

const { initEngine } = require('./engine/index');

// Initialize engine with a manifest
const engine = initEngine('solution-plays/01-enterprise-rag/fai-manifest.json');

if (engine.errors.length > 0) {
  console.error('Engine errors:', engine.errors);
  process.exit(1);
}

// Access wiring status
console.log(engine.status);
// → { play: "01-enterprise-rag", primitives: 10, modules: 4, pillars: 5, ms: 12 }

// Check context resolution
console.log(engine.context.knowledge);
// → ["R2-RAG-Architecture", "O3-MCP-Tools", ...]

// Run evaluation against guardrails
const evaluation = engine.evaluator.check({
  groundedness: 0.97,
  coherence: 0.92,
  relevance: 0.88,
  safety: 0,
  costPerQuery: 0.008,
});
console.log(evaluation);
// → { pass: true, metrics: { groundedness: "PASS", ... } }

Test Results

42/42 PASS

Suite	Tests	Status	Coverage
Manifest Reader	8	8/8	Schema validation, required fields, NN-kebab pattern, semver check
Context Resolver	6	6/6	Knowledge module resolution, WAF pillar validation, scope isolation
Primitive Wirer	10	10/10	Agent/instruction/skill/hook discovery, schema validation, path resolution
Hook Runner	5	5/5	Event dispatch, timeout protection, error isolation, script execution
Evaluator	7	7/7	Threshold checks, score comparison, pass/fail reporting, cost tracking
MCP Bridge	3	3/3	Tool registration, status queries, evaluation passthrough
Integration	3	3/3	End-to-end Play 01 load, full pipeline, error recovery

Configuration Reference

Engine behavior is controlled by the manifest itself — no separate config files needed.

Guardrail Thresholds

Set in primitives.guardrails — groundedness, coherence, relevance (0-1 float), safety (must be 0), costPerQuery (USD). The evaluator checks every response.

Knowledge Modules

Listed in context.knowledge[] — FROOT module IDs like R2-RAG-Architecture. The context-resolver loads the actual documents for injection.

WAF Pillars

Declared in context.waf[] — enum of 6 values. The primitive-wirer ensures every agent and instruction respects the declared pillars.

Hook Events

Hooks fire on 4 lifecycle events: sessionStart, sessionEnd, userPromptSubmitted, preToolUse. Configured in each hook's hooks.json file.

Infrastructure

infrastructure.bicep points to the Azure Bicep template. The engine validates the path exists and can pass it to deployment pipelines.

Toolkit Paths

toolkit.devkit, .tunekit, .speckit point to .github/, config/, and spec/ folders respectively. Used for developer experience tooling.

FAI Protocol Integration

The FAI Engine is the reference implementation of the FAI Protocol. Any runtime that reads fai-manifest.json and follows the wiring specification is a FAI Engine. The protocol is the spec; the engine is one implementation.

Protocol → Engine

The engine reads 7 JSON schemas and executes the wiring spec at runtime

Engine → MCP

MCP Bridge exposes engine operations as standard MCP tools for IDE integration

Engine → CI/CD

FAI Factory runs the engine in CI pipelines for automated validation on every commit

FAI Protocol Solution Plays Primitives Marketplace Back to FrootAI