# Rulvar

> An embeddable TypeScript engine for multi-agent LLM workflows:
> durable (a completed LLM call is never paid for twice),
> budget-bounded, vendor-neutral, observable, and testable.
> No server, no database, no control plane.
> Created and maintained by Oleksiy Stepurenko. Apache-2.0 License.

- Website: https://docs.rulvar.com
- Landing page: https://rulvar.com
- Repository: https://github.com/o-stepper/rulvar
- Maintainer: Oleksiy Stepurenko <step.oleksiy@gmail.com>
- License: Apache-2.0 (© 2026 Oleksiy Stepurenko)

Read [Rulvar for LLMs](https://docs.rulvar.com/guide/llms) first: a single self-contained
orientation page for AI assistants, with the API surface, the rules generated
code must follow, and one canonical program.

## Guide

- [What is Rulvar?](https://docs.rulvar.com/guide): An embeddable TypeScript engine for durable, budget-bounded, testable multi-agent LLM workflows that runs entirely inside your application.
- [Writing a provider adapter](https://docs.rulvar.com/guide/adapter-authors): Implement the ProviderAdapter SPI for a new provider, from wire mapping and streaming obligations through error classification, usage normalization, capability declaration, and cassette contract tests.
- [PlanRunner and extensions](https://docs.rulvar.com/guide/adaptive-orchestration): The opt-in @rulvar/plan extension for wide fan-out workloads, where the task plan is typed engine-owned data with journaled revisions, reuse, escalations, model ladders, and guaranteed termination.
- [Agents](https://docs.rulvar.com/guide/agents): How Rulvar runs agents, covering profiles, the tool loop and turns, structured output tiers, turn-boundary checkpoints, cross-provider history projection, compaction, approval suspensions, and agent-as-tool composition.
- [Architecture](https://docs.rulvar.com/guide/architecture): How Rulvar's twelve components compose across seven layers, the dependency rules that keep the core vendor neutral, and the full package map with its dependency graph.
- [Budgets and termination](https://docs.rulvar.com/guide/budgets): How the three-layer budget bounds run spend to a segment-immutable USD ceiling with at most one turn of overshoot per in-flight agent, and how the frozen termination account guarantees every run ends.
- [CLI, server, and worker](https://docs.rulvar.com/guide/cli): The optional shells in @rulvar/cli: the Rulvar CLI with TUI progress, an embeddable HTTP server with SSE and external resolution endpoints, a lease-fenced queue worker, and the OTel exporter.
- [Cookbook](https://docs.rulvar.com/guide/cookbook): Seven production-shaped recipes over the public Rulvar API, each backed by a runnable integration test in the repository, from evidence-preserving research to isolated tool execution.
- [Data protection](https://docs.rulvar.com/guide/data-protection): PII never persists or emits in plaintext under policy: envelope encryption over the serialization hook with KMS-shaped key management, host redaction patterns at the telemetry boundary, portable run export and import, salted metadata digests, and the audit trail reducer.
- [Determinism lint](https://docs.rulvar.com/guide/determinism): Why Rulvar workflow modules must stay replay-stable and how eslint-plugin-rulvar enforces it with seven flat config rules and structured JSON diagnostics for the planner self-repair loop.
- [Durability and resume](https://docs.rulvar.com/guide/durability): How Rulvar runs survive crashes, restarts, and machine moves: resume semantics, suspended entries, journaled deadlines, turn checkpoints, and at-least-once dispatch that never pays twice.
- [The effect lane](https://docs.rulvar.com/guide/effects): Performing an external effect under a revocable approval with durable evidence: the journaled consumption protocol, the provider capability matrix, crash-window recovery licensed by provider-side fencing, receipts, budgets, quarantine, and the kill point conformance kit.
- [Evals](https://docs.rulvar.com/guide/evals): Quality measurement for Rulvar workflows with golden, rubric, and LLM-judge graders that run through the engine itself, config-matrix comparisons, model sweeps that feed ModelKnowledge, and a canary fingerprint that catches silent model drift.
- [Example patterns](https://docs.rulvar.com/guide/examples): The five quality-pattern recipes shipped in the repository, adversarial panel, judge panel, loop-until-dry, completeness critic, and verifier lane, as runnable workflows over the public ctx API.
- [Installation](https://docs.rulvar.com/guide/installation): Install the @rulvar/rulvar umbrella package or compose individual @rulvar packages. Node.js 22.12 or newer, ESM only, TypeScript recommended.
- [Core invariants](https://docs.rulvar.com/guide/invariants): The six load-bearing guarantees behind every Rulvar run and the mechanism that enforces each one.
- [Isolated executor](https://docs.rulvar.com/guide/isolated-executor): Running tool work out of process so hostile or model-generated scripts cannot reach host capabilities: the ToolExecutorProvider seam, the subprocess and container reference adapters, per-call credentials and the side-effect ledger, and the executable conformance kit.
- [The journal](https://docs.rulvar.com/guide/journal): How Rulvar's content-addressed journal identifies effects, replays paid work on resume, and guarantees you never pay for the same call twice.
- [Journal compatibility](https://docs.rulvar.com/guide/journal-compatibility): How journals survive Rulvar upgrades: per-entry hashVersion, the KeyDeriver support window, JournalCompatibilityError, and frozen profiles from @rulvar/compat.
- [Rulvar for LLMs](https://docs.rulvar.com/guide/llms): A single self-contained orientation page for AI assistants and coding agents, with the exact API surface, the hard rules generated Rulvar code must follow, one canonical program, and pointers to every deeper fact.
- [MCP](https://docs.rulvar.com/guide/mcp): Connect MCP servers as tool sources on the Rulvar tool bus, with the same permission chain, journal semantics, and toolset identity as native tools.
- [Model knowledge](https://docs.rulvar.com/guide/model-knowledge): A per-project, append-only knowledge base of model suitability. Verified eval claims and editorial notes with provenance, a journal-pinned knowledge card that teaches orchestrators what to spawn, TTL decay, falsification sweeps, and the canary fingerprint.
- [Model routing](https://docs.rulvar.com/guide/model-routing): How Rulvar resolves a model for every invocation through the call, profile, workflow, and engine layers, routes seven invocation roles across providers, scrubs capabilities, enforces role quality floors, and prices usage from a versioned price table.
- [Observability](https://docs.rulvar.com/guide/observability): One typed WorkflowEvent stream feeds host subscriptions, cost reports, metrics, and the OpenTelemetry exporter, with replay re-emission and default-on secret masking built in.
- [The operational host](https://docs.rulvar.com/guide/operational-host): The operational host reference (RV1705) - per-tenant engines by construction, revocable approvals, idempotent guarded effects, and the decision-chain audit fold, each proven by an executed example.
- [Orchestration modes](https://docs.rulvar.com/guide/orchestration-modes): The three ways to drive a Rulvar run, human scripts, planner-written scripts in the worker sandbox, and the dynamic orchestrator agent, all on one runtime, one journal, and one budget path.
- [Machine-written scripts](https://docs.rulvar.com/guide/planner): How @rulvar/planner has a plan model write a frozen workflow script, self-repairs it from structured lint diagnostics, and executes it deterministically in the worker sandbox.
- [The production host reference](https://docs.rulvar.com/guide/production-host): The production host dossier (RV4307): the RACI of a production deployment, the runnable identity, routing, floor, and gate pieces, and the promotion evidence, with every example labeled Fake/VCR evidence and never production proof.
- [Production profiles](https://docs.rulvar.com/guide/production-profiles): Documented postures for running rulvar in production: read-only diagnosis, isolated patch, the one-call regulated floor, and the merge/deploy authority the library deliberately does not claim, each composed from features the other guides define.
- [Providers](https://docs.rulvar.com/guide/providers): The ProviderAdapter SPI and the shipped adapters, including @rulvar/anthropic, @rulvar/openai with the openaiCompatible factory, and @rulvar/bridge-ai-sdk for any Vercel AI SDK LanguageModelV4 model, plus every supported credential mode from API keys to workload identity federation.
- [Quickstart](https://docs.rulvar.com/guide/quickstart): Install Rulvar, run a parallel judge panel under an immutable dollar budget, then resume the run and watch every completed model call replay from the journal for free.
- [Writing a store](https://docs.rulvar.com/guide/store-authors): How to implement a JournalStore, the lease capability, and a TranscriptStore against the frozen storage seam, and certify the result with @rulvar/store-conformance.
- [Stores](https://docs.rulvar.com/guide/stores): Where run truth lives - the five-method journal store SPI, leases with fencing epochs for queue workers, transcript and model-knowledge stores, and the shipped in-memory, JSONL, SQLite, and PostgreSQL implementations.
- [Testing](https://docs.rulvar.com/guide/testing): How to test agent workflows with zero live model calls using the FakeAdapter test engine, VCR cassettes with record-time redaction, replay-strict journal runs, and the shipped Vitest and Jest matchers.
- [Tools and permissions](https://docs.rulvar.com/guide/tools): Defining typed tools with tool() and SchemaSpec, how toolsetHash makes tool identity replay-safe, executors and worktree isolation, the layered permission chain, ask-approval suspensions, and how tool results reach the journal.
- [Troubleshooting](https://docs.rulvar.com/guide/troubleshooting): Symptom-first fixes for first-run setup failures, missing API keys, unexpected reruns, journal compatibility errors, early budget exhaustion, stuck runs, determinism lint failures, provider errors, and orphaned journal entries.
- [Workflows and ctx](https://docs.rulvar.com/guide/workflows): Write durable multi-agent workflows as plain async functions over the injected ctx surface, run them with createEngine, and keep every effect replayable.

## Reference

- [Changelog](https://docs.rulvar.com/reference/changelog): Per-package release notes for the @rulvar packages, aggregated from the Changesets changelogs.
- [Design principles](https://docs.rulvar.com/reference/design-principles): The seven hard goals behind Rulvar, the concrete mechanism that enforces each one, the design stances, and the features deliberately left out.
- [FAQ](https://docs.rulvar.com/reference/faq): Honest answers to the questions Rulvar users actually ask, covering comparisons with graph frameworks and workflow engines, storage, budgets, local models, replay, the security posture, runtime support, and licensing.
- [Glossary](https://docs.rulvar.com/reference/glossary): The canonical vocabulary used throughout the Rulvar documentation, grouped by subsystem.
- [Packages](https://docs.rulvar.com/reference/packages): The authoritative table of every Rulvar package, with layer placement, key exports, dependencies, the dependency graph, and the lockstep versioning policy.
- [Versioning and releases](https://docs.rulvar.com/reference/versioning): How Rulvar versions and releases - lockstep semver across the fixed group, the @rulvar/compat exemption, the journal support window, changesets-driven changelogs, and provenance-attested publishing.

## Contributing

- [Contributing](https://docs.rulvar.com/contributing): How to set up the repository, the development workflow, and the project conventions.
- [RFC: fenced run state](https://docs.rulvar.com/contributing/rfc-fenced-run-state): Design proposal to fence every durable run mutation behind the lease epoch: the audit that motivates it, the reference store fix that shipped with it, and a phased, additive store SPI evolution.

## Optional

- [API reference index](https://docs.rulvar.com/llms-api.txt): one line per generated API page
- [Full documentation snapshot](https://docs.rulvar.com/llms-full.txt): concatenated Markdown of every published page