Release Notes

What shipped in each version of the BOA Framework.

@boa-framework/core — v0.1.0

Initial Release — The core engine and CLI toolchain for building modular, composable backend systems from small, isolated blocks with explicit contracts.

Highlights

  • AI-native by design — Every block carries INTENT, RULE, FIXTURE, and TAGS metadata so AI assistants always know why a block exists, what constraints it must obey, and how to verify it.
  • .boa declarative format — A human-readable, AI-friendly alternative to JSON for manifests, workflows, registries, and project files.
  • Universal Runtime Protocol (URP) — A language-agnostic stdin/stdout JSON contract that lets blocks run in Node.js, Python, or any future runtime without changing the orchestration layer.
  • Self-testing blocks — FIXTURE declarations embed expected input/output pairs directly in the manifest. No separate test files needed.
  • Impact analysis — Before changing a block, see every workflow and downstream consumer it touches.

CLI Commands

Command Description
boa init [dir] Scaffold a new project with layer directories, registry, project manifest, and AI instruction files
boa block create <name> Generate a new block with manifest, entry file, and test template
boa workflow-create <name> Generate a new workflow skeleton
boa run <workflow.boa> Execute a workflow end-to-end with --input-file support
boa test <Block@version> Run all FIXTURE and MOCK declarations for a block
boa validate Validate all manifests, fixtures, mocks, and workflow wiring
boa impact <Block@version> Show where a block is used, what depends on it, and which outputs are consumed
boa registry-ls List all registered blocks with paths

Block System

  • 6 block layers — Primitive, Capability, Domain, Workflow, UI Block, UI Capability
  • Polyglot runtimes — Node.js and Python adapters ship out of the box; extensible to Go, Rust, C#, Java, WASM, and HTTP
  • Explicit I/O contracts — Typed IN / OUT fields with required (!) and optional (?) markers
  • Dependency tracking — DEPS declarations for block-to-block dependencies
  • Error taxonomy — ERR declarations with predefined URP error types (ValidationError, DependencyError, RuntimeError, SchemaMismatch, ExecutionTimeout)

Workflow Engine

  • Sequential execution with automatic data flow between steps via MAP directives
  • Parallel step groups — PARALLEL / END_PARALLEL blocks for concurrent execution
  • Conditional steps — WHEN clauses that reference previous step outputs
  • Error strategies — Per-step ON_ERROR with fail, skip, or retry semantics
  • Workflow-level error handler — Global ON_ERROR block for graceful degradation
  • Configuration injection — CONFIG key-value pairs available to all steps
  • Sub-workflows — SUB keyword for composing workflows within workflows
  • Execution metrics — Duration tracking and step completion counts

.boa Parser & Serializer

  • Full round-trip support: parse .boa text to typed objects and serialize back
  • Supports block.boa, workflow.boa, blocks.boa (registry), and project.boa
  • Comment stripping, fixture/mock parsing, field schema inference

Project Scaffolding

  • Generates organized directory structure by layer
  • Embeds AI assistant instructions for Claude Code, Cursor, and GitHub Copilot
  • Creates starter project.boa and blocks.boa files

Programmatic API

import {
  parseBlockBoa,
  parseWorkflowBoa,
  parseRegistryBoa,
  parseProjectBoa,
  serializeBlockBoa,
  serializeWorkflowBoa,
  serializeRegistryBoa,
  serializeProjectBoa,
  BlockRegistry,
  BlockLoader,
  WorkflowEngine,
  WorkflowContext,
  NodeRuntimeAdapter,
  PythonRuntimeAdapter,
  getRuntimeAdapter,
  readStdin,
} from "@boa-framework/core";

Supported Platforms

  • Node.js v18+ (v22 recommended)
  • Windows, macOS, Linux
Windows Users Use --input-file instead of piping JSON via echo. Windows echo strips double quotes from JSON strings.

Installation

npm install -g @boa-framework/core
boa --help

Roadmap

  • Additional runtime adapters (Go, Rust, C#, WASM, HTTP)
  • Block marketplace and sharing
  • Remote workflow execution
  • Streaming step outputs

@boa-framework/ui — v0.1.0

Initial Release — The browser companion to @boa-framework/core. Brings BOA's block-orchestrated architecture to frontend applications with composable UI logic, workflow orchestration, automatic memoization, and sandbox isolation.

Highlights

  • Pure UI blocks — Side-effect-free functions whose results are automatically memoized. Inputs are deep-frozen to enforce immutability.
  • UI capability blocks — Blocks that are allowed to perform side effects (fetch, localStorage, clipboard) with explicit permission declarations.
  • Browser workflow engine — The same sequential/parallel/conditional workflow model from the backend, adapted for in-browser execution.
  • React hooks — First-class React integration via useWorkflow with loading/error/result state management.
  • Sandbox isolation — Pure blocks are monitored for global state mutations; violations throw at runtime.

SDK

import { createBoaUI } from "@boa-framework/ui";

const boa = createBoaUI({ maxMemoEntries: 200 });

// Register from .boa manifests
boa.registerBlockFromBoa(boaText, "./blocks/formatPrice.js");
boa.registerWorkflowFromBoa(workflowBoaText);

// Execute
const result = await boa.run("CheckoutWorkflow", { cartId: 42 });
Method Description
run(name, input) Execute a registered workflow
registerBlock(def) Register a UI block definition
registerWorkflow(def) Register a workflow definition
registerBlockFromBoa(text, entry) Parse .boa manifest and register
registerWorkflowFromBoa(text) Parse .boa workflow and register
clearMemoCache() Clear the memoization cache

Workflow Engine

  • Sequential execution — Steps run in order with MAP data flow
  • Parallel execution — Steps inside PARALLEL / END_PARALLEL run concurrently via Promise.all
  • Conditional steps — WHEN clauses with comparison operators (>, <, ===, !==, >=, <=)
  • Sub-workflows — Nest workflows within workflows using SUB
  • Error handling — Workflow-level ON_ERROR block for graceful recovery
  • Path resolution — $steps.stepId.output.field, $initial.field, $config.key references resolved automatically

Sandbox & Permissions

Pure blocks (ui-block):

  • Inputs are deep-frozen before execution
  • Global state (globalThis) is monitored for mutations
  • Results are automatically cached in MemoCache
  • All side effects denied (no fetch, storage, clipboard, or DOM)

Capability blocks (ui-capability):

  • Side effects permitted: fetch, localStorage, clipboard
  • DOM access denied by default
  • No memoization (results may differ between calls)

Memoization

  • LRU-style eviction when maxMemoEntries is reached (default: 100)
  • Cache key: blockName:JSON.stringify(input)
  • Only applied to pure ui-block layer blocks
  • Manual cache clearing via boa.clearMemoCache()

React Integration

import { createBoaUI, createBoaHooks } from "@boa-framework/ui";

const boa = createBoaUI();
const { useWorkflow, ensureReact } = createBoaHooks(boa);

// In a component
function Cart() {
  const { result, loading, error, run } = useWorkflow("CartWorkflow");

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;
  return <div>{JSON.stringify(result)}</div>;
}
  • useWorkflow(name, input?) — Returns { result, loading, error, run }
  • React is lazy-loaded (not a hard dependency)
  • ensureReact() pre-loads React before first render

Observability

import { createBoaUI, consoleLogger } from "@boa-framework/ui";

const boa = createBoaUI({
  ...consoleLogger("[my-app]"),
});
Callback Fires when
onStepStart(stepId, input) A step begins execution
onStepEnd(stepId, output, durationMs) A step completes successfully
onStepSkip(stepId, reason) A step's WHEN condition is false
onStepError(stepId, error) A step throws an error

Runtimes

Runtime Status Description
js Shipped Browser JavaScript via dynamic import() with module caching
wasm Stub WebAssembly interface defined, implementation pending

Programmatic API

import {
  // SDK
  createBoaUI,
  createBoaHooks,

  // Engine & Registry
  UIWorkflowEngine,
  UIBlockRegistry,

  // Runtime
  JSRuntime,
  WASMRuntime,
  MemoCache,
  getRuntimeForBlock,

  // Sandbox
  runInSandbox,
  PURE_BLOCK_PERMISSIONS,
  CAPABILITY_BLOCK_PERMISSIONS,

  // Utilities
  deepResolve,
  evalCondition,
  consoleLogger,
} from "@boa-framework/ui";

Build Target

  • ES2022 module format, Bundler module resolution
  • Compatible with modern bundlers (Vite, webpack 5, esbuild, Rollup)
  • Peer dependency: @boa-framework/core

Roadmap

  • WASM runtime implementation
  • DOM-scoped capability permissions
  • Block hot-reloading for development
  • DevTools browser extension for workflow visualization
  • Server-side rendering support