Boruna

v3.0.0 is the current release. The 1.x line remains under long-term support — active through 2027-11-15, security through 2028-05-15. See docs/lts.md for support windows, deprecation policy, and security-backport SLAs.

Deterministic, policy-gated workflow execution for AI systems that must be auditable.

The problem

Most AI orchestration tools run workflows and return outputs. When something goes wrong — or when a regulator asks — there is no reliable way to answer: What exactly ran? What did the model see? What did it return? Can you prove it?

Boruna answers those questions by design.

Every Boruna workflow run produces a tamper-evident evidence bundle: a hash-chained audit log of every step executed, every capability invoked, every model response received. That bundle can be inspected, verified, and replayed — without network access, without a central server, without trusting anyone’s word.

This makes Boruna suited for teams building AI workflows that touch regulated data, make consequential decisions, or need a defensible audit trail.

What Boruna provides

• DAG workflow execution — steps are .ax source files; the workflow is a workflow.json DAG definition (schema_version: 1 frozen at 1.0)
• Capability enforcement — every side effect (LLM calls, HTTP, database, filesystem) is declared and policy-gated at the VM level
• Evidence bundles — hash-chained tamper-evident logs, written automatically with --record. Optional AES-256-GCM envelope encryption for compliance-sensitive deployments. evidence inspect shows step output content for plaintext bundles.
• Deterministic replay — re-execute any recorded workflow with identical outputs, verified by the VM
• Approval gates — pause workflow execution for human review or external triggers before continuing
• Diagnostics, auto-repair, and migration — boruna lang check, boruna lang repair, boruna migrate for .ax files and bundle/workflow upgrades
• boruna new — interactive scaffold for new workflows from templates
• 33 built-in functions — string (12), list (7), and map (7) operations plus type conversions and debug builtins (__builtin_string_*, __builtin_list_*, __builtin_map_*, …) available in every .ax file without imports
• Import resolution — import "std-name" inlines libs/<name>/src/core.ax at compile time; 14 stdlib packages (the original 13 are 1.0-stable)
• Four formal versioned specifications — .ax language 1.0, bytecode 1.0, evidence bundle format 1.0, workflow DAG schema 1.0 (all under docs/spec/)
• MCP server — exposes 14 tools for AI coding agent integration (Claude Code, Cursor, Codex)

What Boruna is not

• Not a general-purpose language or runtime (use Rust, Python, Go for that)
• Not an LLM framework (use LangChain, LCEL, etc. for prompt engineering)
• Not a cloud service (Boruna runs wherever you deploy it)
• Not a key-management system (operators wire HSM / KMS integration themselves; bundle-encryption KEK lifecycle is operator-owned)

Install

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/escapeboy/boruna/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/escapeboy/boruna/master/install.ps1 | iex

Both scripts pick the right build for your OS and CPU, check it against the release’s SHA256SUMS and refuse to install on a mismatch, then put boruna, boruna-mcp, boruna-pkg and boruna-orch in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\boruna\bin, added to your user PATH). Set BORUNA_VERSION=v3.4.0 to pin a version or BORUNA_INSTALL_DIR to choose the folder. Read install.sh / install.ps1 first if you prefer not to pipe a script into your shell.

Check the installation with boruna --version and boruna doctor.

# Linux x86_64 (musl — works on Alpine, Ubuntu, Debian, ...)
curl -fsSL https://github.com/escapeboy/boruna/releases/latest/download/SHA256SUMS -o SHA256SUMS
TARGET=x86_64-unknown-linux-musl
TAR=$(grep "$TARGET" SHA256SUMS | awk '{print $2}')
curl -fsSLO "https://github.com/escapeboy/boruna/releases/latest/download/$TAR"
grep "$TAR" SHA256SUMS | sha256sum -c -
tar -xzf "$TAR"
./boruna-*-${TARGET}/boruna --version

$base = "https://github.com/escapeboy/boruna/releases/latest/download"
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS
$target = "x86_64-pc-windows-msvc"   # or aarch64-pc-windows-msvc on Windows on Arm
$zip = ((Select-String -Path SHA256SUMS -Pattern $target).Line -split "\s+")[1].TrimStart("*")
Invoke-WebRequest "$base/$zip" -OutFile $zip
# Compare this hash with the line for $zip in SHA256SUMS:
(Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()
Expand-Archive $zip -DestinationPath .
.\boruna-*-$target\boruna.exe --version

Supported platforms

Every platform below is built and its full test suite is run natively on a real machine of that type in CI (no emulation), together with an example workflow and evidence verify.

Other targets (FreeBSD, 32-bit, RISC-V and so on) are not built or tested; build from source and run cargo test --workspace to see whether they work for you. See docs/releasing.md.

Or build from source:

git clone https://github.com/escapeboy/boruna
cd boruna
cargo build --workspace --release

Quickstart

# Run a workflow
boruna workflow run examples/workflows/llm_code_review --policy allow-all --record

# Verify the evidence bundle
boruna evidence verify .boruna/runs/<run-id>/

→ Full Quickstart — 10 minutes, ends with a verified evidence bundle.

Example workflows

Each example runs in demo mode (no external services) and produces a verifiable evidence bundle.

How the evidence guarantee works

workflow.json  →  DAG Validator  →  Step Runner
                                        ↓
                                   .ax source
                                        ↓
                                   Compiler → Bytecode
                                        ↓
                                   VM (capability gateway)
                                        ↓
                                   EventLog entry (CapCall + CapResult)
                                        ↓
                              Hash-chained audit log

boruna evidence verify <bundle>
  → Chain integrity: VALID
  → All step hashes: MATCH
  → Verification: PASSED

Every CapCall (including LLM calls) is logged with its full response. The log is SHA-256 hash-chained from a genesis entry containing the workflow definition hash. Modification of any entry breaks the chain.

Architecture

Boruna is a Rust workspace with 10 production crates plus a benches/ member:

1175+ tests across 11 workspace members. cargo test --workspace — all pass.

Documentation

Status

Boruna is at v3.0.0 — the release that removes the entire HTTP / serving / distributed-execution layer. Gone are the distributed coordinator, distributed workers, active-active HA and coordinator mTLS, the three web UIs (workflow dashboard, evidence web viewer, approval console), and the serve cargo feature and its server dependencies. What remains is a local deterministic engine and CLI: compiler → capability-gated VM → orchestrator (runner, persistence, audit) → tamper-evident evidence bundles. Approval and external-trigger gates are still handled locally via boruna workflow approve/reject/trigger plus resume. This is a breaking release — the coordinator, dashboard, worker, and evidence serve CLI commands, the --coordinator / --coord-token flags, and the serve feature are removed — so review the 3.0.0 entry in CHANGELOG.md. The core execution engine, evidence bundles, and four formal versioned specifications (.ax language, bytecode, workflow DAG, evidence bundle) remain feature-complete; the 1.x LTS line continues per docs/lts.md.

The project is suited for evaluation, internal tooling, and audit-sensitive AI pipelines. Operator action: validate the docs/PERFORMANCE.md budget against your workload, and review docs/limitations.md for known constraints. External security audit booking is the Q4 2026 commitment in lts.md.

See docs/stability.md for the stability tier breakdown.

For coding agents

Boruna exposes an MCP server for AI coding agent integration. See AGENTS.md for integration instructions and the tool reference.

Contributing

See CONTRIBUTING.md. The short version: open an issue, implement with tests, run cargo test --workspace + cargo clippy + cargo fmt, add a CHANGELOG entry, open a PR.

License

MIT — Copyright 2026 Boruna Contributors

Edit this page on GitHub

Quickstart

Get from zero to a running workflow with an evidence bundle in about 10 minutes.

Prerequisites

• Rust 1.75+ (rustup update stable)
• Git

1. Build

git clone https://github.com/escapeboy/boruna
cd boruna
cargo build --workspace

This builds all 11 workspace members (10 production crates + benches/). Expect 1-2 minutes on first build.

No Rust? Install the prebuilt binaries instead (see Install), still clone the repository for the examples, and write boruna wherever this guide says cargo run --bin boruna --.

2. Run hello world

cargo run --bin boruna -- run examples/hello.ax

Expected output:

Hello, Boruna!

This compiles hello.ax to bytecode and runs it on the VM. No capabilities are needed.

3. Run a workflow

Boruna workflows are DAGs — directed acyclic graphs of steps. Each step is a .ax file that compiles independently and runs in isolation.

Run the LLM code review workflow (in demo mode — no real LLM calls):

cargo run --bin boruna -- workflow run examples/workflows/llm_code_review \
  --policy allow-all

Expected output:

Running workflow: llm_code_review

  [1/3] fetch_diff    → ok
  [2/3] analyze       → ok
  [3/3] report        → ok

Workflow completed in 0.03s

Three steps ran in topological order: fetch a diff, analyze it, produce a report. In demo mode the steps return representative data without calling any external services.

4. Record an evidence bundle

Add --record to capture a tamper-evident log of the run:

cargo run --bin boruna -- workflow run examples/workflows/llm_code_review \
  --policy allow-all --record

Expected output:

Running workflow: llm_code_review

  [1/3] fetch_diff    → ok
  [2/3] analyze       → ok
  [3/3] report        → ok

Workflow completed in 0.03s
Bundle written to: .boruna/runs/20260319-120000-abc12/

5. Inspect the evidence bundle

cargo run --bin boruna -- evidence inspect .boruna/runs/20260319-120000-abc12/

Expected output:

Run ID:     20260319-120000-abc12
Workflow:   llm_code_review
Started:    2026-03-19T12:00:00Z
Completed:  2026-03-19T12:00:00Z
Policy:     allow-all
Steps:      3 completed, 0 failed

Step Results:
  fetch_diff   → ok  (0.0s)
  analyze      → ok  (0.0s)
  report       → ok  (0.0s)

Chain:      valid (3 entries, no gaps)

6. Verify the evidence bundle

cargo run --bin boruna -- evidence verify .boruna/runs/20260319-120000-abc12/

Expected output:

Chain integrity: VALID
All step hashes: MATCH
Environment fingerprint: PRESENT
Verification: PASSED

The hash chain is unbroken. No step output was modified. This is what makes Boruna useful for audit: you can present this bundle, and anyone with the boruna binary can verify it independently.

What you just saw

• Deterministic execution: same workflow definition → same outputs, every time
• Capability policy: --policy allow-all controls what side effects are permitted
• Evidence bundle: a tamper-evident directory written alongside every recorded run
• Independent verification: evidence verify needs no network access, no central server

Try the other workflows

# Document processing with fan-out parallelism
cargo run --bin boruna -- workflow run examples/workflows/document_processing \
  --policy allow-all --record

# Customer support triage with an approval gate
cargo run --bin boruna -- workflow run examples/workflows/customer_support_triage \
  --policy allow-all --record

Run the tests

cargo test --workspace --features boruna-cli/serve

1175+ tests across all workspace members. All should pass.

Next steps

• Write a workflow: Your First Workflow
• Understand the language: .ax Language Reference
• Understand determinism: Determinism
• Understand capabilities: Capabilities
• See all CLI commands: CLI Reference
• Check maturity status: Stability

Edit this page on GitHub

Your First Workflow

This guide walks through creating a simple two-step workflow from scratch, running it, and inspecting the evidence it produces.

Time required: ~15 minutes Prerequisites: Boruna built (cargo build --workspace)

What you’ll build

A workflow that fetches a number and doubles it — two steps connected in sequence. Simple enough to fit in your head, realistic enough to demonstrate every core concept: DAG definition, .ax step code, capability policies, and evidence.

Step 1: Create the workflow directory

mkdir -p my-first-workflow/steps
cd my-first-workflow

Step 2: Define the workflow DAG

Create workflow.json:

{
  "id": "double-it",
  "name": "Double It",
  "description": "Fetch a number, double it, return the result.",
  "steps": [
    {
      "id": "fetch",
      "name": "Fetch Number",
      "source": "steps/fetch.ax",
      "capabilities": []
    },
    {
      "id": "double",
      "name": "Double It",
      "source": "steps/double.ax",
      "capabilities": [],
      "depends_on": ["fetch"]
    }
  ],
  "edges": [
    { "from": "fetch", "to": "double" }
  ]
}

The depends_on field defines the DAG edge. double runs after fetch completes.

Step 3: Write the step files

steps/fetch.ax — returns a number (demo mode; live mode would call net.fetch):

fn get_number() -> Int {
    42
}

fn main() -> Int {
    let n: Int = get_number()
    n
}

steps/double.ax — doubles the input:

fn double(n: Int) -> Int {
    n * 2
}

fn main() -> Int {
    let input: Int = 42
    let result: Int = double(input)
    result
}

Step 4: Validate the workflow

Before running, validate the DAG structure:

cd ..
cargo run --bin boruna -- workflow validate my-first-workflow/

# Expected output:
# Workflow 'double-it': valid
# Steps: 2
# Edges: 1
# Topological order: fetch → double
# No cycles detected.

Validation checks: all referenced step files exist, the graph is acyclic, and every depends_on refers to a real step.

Step 5: Run the workflow

cargo run --bin boruna -- workflow run my-first-workflow/ --policy allow-all

# Expected output:
# Running workflow: double-it
#
#   [1/2] fetch     → ok
#   [2/2] double    → ok
#
# Workflow completed in 0.01s
# Output: 84

Step 6: Run with evidence recording

cargo run --bin boruna -- workflow run my-first-workflow/ --policy allow-all --record

# Expected output:
# Running workflow: double-it
# ...
# Workflow completed in 0.01s
# Bundle written to: .boruna/runs/20260319-120000-abc12/

Step 7: Inspect the evidence

cargo run --bin boruna -- evidence inspect .boruna/runs/20260319-120000-abc12/

# Expected output:
# Run ID:     20260319-120000-abc12
# Workflow:   double-it
# Started:    2026-03-19T12:00:00Z
# Completed:  2026-03-19T12:00:00Z
# Policy:     allow-all
# Steps:      2 completed, 0 failed
#
# Step Results:
#   fetch    → ok  (0.0s)
#   double   → ok  (0.0s)
#
# Chain:      valid (2 entries, no gaps)

Step 8: Verify the evidence bundle

cargo run --bin boruna -- evidence verify .boruna/runs/20260319-120000-abc12/

# Expected output:
# Chain integrity: VALID
# All step hashes: MATCH
# Environment fingerprint: PRESENT
# Verification: PASSED

That’s a complete workflow: defined, validated, executed, recorded, and verified.

What just happened

1. The workflow runner read workflow.json and sorted steps topologically.
2. Each .ax file was compiled to bytecode and run on the VM.
3. Every step’s output was captured and written to the evidence bundle.
4. The audit log was hash-chained so no entry can be modified undetected.
5. evidence verify confirmed the chain was unbroken.

Next steps

• Add a real capability: modify steps/fetch.ax to declare !{net.fetch} and run with --live
• See a production-scale example: examples/workflows/llm_code_review
• Add an approval gate: customer support triage workflow
• Read the .ax language reference

Edit this page on GitHub

Limitations

Boruna has real constraints. This document describes them clearly, so you can make an informed decision about whether it fits your use case.

Language limitations

Values are immutable; only let mut bindings can be rebound. Records, lists and maps are never changed in place; state transitions use record spread (State { ..old, field: new_value }). A let mut binding can point to a new value (total = total + 1), which is enough for counters and accumulators but not for shared mutable state.

Loops are basic. There are while and for x in list loops, but no break, continue or loop, and for only iterates lists. The step limit stops a loop that never ends, and deep recursion can also hit it.

Some type checks are not enforced yet. Assigning a value of a different type to a let mut binding, using a non-Bool while condition, and reassigning a binding declared without mut all compile today (the last one is warning E010). See the language spec §4.5.

No generics. Types in .ax are concrete at definition time. There is no generic type system. This keeps the language simple but limits abstraction.

No imports. .ax files cannot import other .ax files. Standard library access is through the package system, not file imports. Large workflows are composed at the workflow DAG level, not at the language level.

String processing is limited. The standard library provides basic string operations, but .ax is not designed for complex text transformation. Use LLM capabilities for natural language processing; use compiled Rust for heavy text manipulation.

VM limitations

Step limit is a blunt instrument. The --step-limit flag prevents runaway execution but does not provide fine-grained CPU time control. A step that does 10M arithmetic operations may run longer than expected before hitting the limit.

Wave-based concurrent execution, not full DAG parallelism. The runner processes steps in topological waves with --concurrency <N> workers per wave (sprint 0.3-S4). A slow step at level N blocks fast steps at level N+1 even if they don’t actually depend on the slow one. A full DAG-based scheduler (no wave boundaries) is not yet implemented.

Actor system is single-process. Actors run in the same OS process with round-robin scheduling. There is no distributed actor execution.

Memory is unbounded within a step. The VM does not enforce memory limits on individual step execution. A step that allocates large lists or maps may use significant memory.

Capability limitations

The HTTP handler requires a feature flag. Real HTTP calls require building with --features boruna-cli/http. This is a build-time decision, not a runtime one.

LLM calls use Bring Your Own Handler (BYOH). The llm.call capability is declared and enforced by the VM, and boruna-effect provides prompt / cache / context primitives — but no default network-calling handler ships in core. Wire your provider (OpenAI, Anthropic, vLLM, Ollama, custom router) by implementing CapabilityHandler and passing it to CapabilityGateway::with_handler. See LLM Integration Guide for the contract, examples, and rationale. A reference OpenAI handler lives at examples/llm_handlers/openai/.

No streaming. Capability calls are synchronous and blocking. LLM responses must complete before the step continues. This is unsuitable for streaming chat interfaces.

SSRF protection is allowlist-based. The HTTP handler rejects private IP ranges and localhost, but allowlisting specific domains requires extending the NetPolicy struct. There is no UI for this.

Workflow limitations

Wall-clock-keyed enforcement is non-deterministic on failure. Limits like max_wall_ms are wall-clock-keyed: a workflow that completes within budget produces deterministic output, but one that times out may finish on a fast machine and time out on a slow one. Documented per integrator surface (limits, OTel spans).

Evidence and audit limitations

Evidence bundles are local files; remote storage is operator-owned. Evidence bundles write to <data-dir>/runs/<run-id>/. Pluggable storage adapters (S3 / object storage / document store) are roadmap 0.7.x or 1.x. Today, ship bundles to remote storage with your own pipeline (rsync, S3 upload, etc.).

LLM response reproducibility is not guaranteed. Evidence bundles capture LLM responses for replay, but if the LLM provider changes their model weights, a replay may produce different outputs if the real capability is used. Replay with recorded responses (sprint 0.5-S7 of FleetQ track) is always reproducible.

Evidence bundle encryption KEK is operator-managed. Sprint W6-B added envelope AES-256-GCM encryption — operators supply the KEK via env var or CLI flag. Boruna does not ship key management (no HSM/KMS integration); KEK lifecycle (storage, rotation, sealing) is the operator’s responsibility. Key rotation tooling is roadmap.

Plaintext bundle.json metadata. Even with --encrypt-bundle, the top-level bundle.json manifest is plaintext (chicken-and-egg with the wrapped DEK). It carries format_version, boruna_version, run_id, workflow_hash, and the wrapped DEK envelope. Run identifiers may be visible to a bundle inspector even when payload bytes are encrypted.

Operational limitations

Multi-tenancy is environment-namespaced, not cryptographically isolated. The --env flag (sprint 0.4-S14) namespaces the data-dir and Prometheus labels per-environment. This separates run histories but does not provide cryptographic isolation between tenants — that requires OS-level separation or per-tenant deployments.

Minimum Rust version: 1.75.0. Teams running older Rust toolchains will need to upgrade.

What to do if these limitations block you

File an issue at https://github.com/escapeboy/boruna. Limitations that frequently block real use cases will be prioritized in the roadmap.

See also: Roadmap, Stability

Edit this page on GitHub

Frequently Asked Questions

What problem does Boruna solve?

Most AI workflow orchestration tools are wrappers around LLM API calls with some retry logic and prompt templates. They work fine for demos. They break down when you need to answer questions like: “What exactly did the model see?”, “Can I prove this workflow ran correctly?”, “If I re-run this tomorrow, will I get the same result?”

Boruna is built for teams that need answers to those questions — because they operate in regulated environments, because their AI workflows make consequential decisions, or because they’ve been burned by non-reproducible outputs.

The core value proposition: every workflow run produces a tamper-evident evidence bundle. You can verify it independently, replay it exactly, and present it in an audit.

How is Boruna different from LangChain, LlamaIndex, or similar frameworks?

LangChain and similar frameworks are excellent for building LLM-powered applications quickly. They are not designed for auditability or deterministic replay.

Boruna’s design priorities are different:

These are different tools for different requirements. A team building a chatbot should probably use LangChain. A team running AI-assisted financial analysis in a regulated environment should look at Boruna.

How is Boruna different from Temporal or similar workflow engines?

Temporal is a durable workflow engine with excellent reliability guarantees. It is not specifically designed for AI workflows or LLM governance.

Boruna focuses on:

• Capability policy: declaring and enforcing what LLM calls and network requests are permitted
• Evidence bundles: cryptographic proof of what ran and what the model returned
• Determinism as a contract: same inputs → same outputs, enforced by the VM
• The .ax language: pure, typed, auditable step code that compiles to bytecode

Temporal is a better choice if you need multi-step business processes with human tasks, timers, and at-least-once execution guarantees. Boruna is a better choice if governance and auditability of AI-specific workflows is the primary concern.

Is .ax Turing-complete?

Yes. .ax supports recursion and is Turing-complete in the theoretical sense. In practice, the --step-limit flag on boruna run enforces a bound on VM steps, which prevents runaway execution in production workflows.

Can I call external APIs and LLMs?

Yes, but they must be declared as capabilities. A step that calls an LLM must annotate its function with !{llm.call}. A step that makes HTTP requests must declare !{net.fetch}.

In demo mode (default), capability calls are stubbed. In --live mode (with the http feature), real HTTP requests are made against the SSRF-protected handler.

Does Boruna guarantee that LLM outputs are reproducible?

No. LLMs are probabilistic. Running the same prompt twice will produce different outputs. Boruna cannot change this.

What Boruna guarantees: the LLM response is recorded in the evidence bundle. If you replay the workflow from its evidence bundle, the recorded response is substituted — so the replay is deterministic even if the original call wasn’t.

This lets you verify that a workflow produced a specific output on a specific run, without requiring the LLM to reproduce the response.

What is the evidence bundle format?

A directory containing:

• manifest.json — run metadata
• audit_log.json — hash-chained step execution log
• events/event_log.json — full capability call stream
• steps/<step-id>.input and .output — step I/O
• env_fingerprint.json — runtime environment snapshot

See Evidence Bundles for the full specification.

Can I use Boruna without the .ax language?

Not currently. The VM, capability enforcement, and determinism guarantees are tied to .ax bytecode. Compiling other languages to Boruna bytecode is technically possible but not a current project goal.

What Rust version does Boruna require?

Minimum supported Rust version: 1.75.0 (stable). No nightly features are required.

Is there a hosted version?

Not yet. Boruna runs locally or in whatever environment you deploy it to. A hosted platform is on the long-term roadmap.

How do I report a security vulnerability?

See SECURITY.md. Use GitHub Security Advisories for responsible disclosure. Do not file a public issue.

Is Boruna production-ready?

Boruna is at 1.3.0, on the 1.x LTS line. The core engine, workflow DAG, evidence bundles, capability enforcement, and all 13 stdlib packages are stable and LTS-protected. External security audit is booked for Q4 2026. See Stability for the full maturity assessment and lts.md for the support contract.

How do I contribute?

See CONTRIBUTING.md. The short version: open an issue, fork, implement, run cargo test --workspace + cargo clippy + cargo fmt, and open a PR with a CHANGELOG entry.

Edit this page on GitHub

Determinism in Boruna

Determinism is Boruna’s foundational guarantee: given the same workflow definition, the same inputs, and the same capability responses, execution produces identical outputs every time, on every machine.

This is not a convention or a best-effort property. It is structurally enforced by the runtime.

Why determinism matters

AI systems are inherently probabilistic. LLMs return different outputs on repeated calls. Network responses vary. Clocks differ between machines. In ad hoc orchestration this is accepted as normal. In regulated environments, it creates a compliance problem: you cannot audit what you cannot reproduce.

Boruna’s answer is to treat non-determinism as a capability, not a default. Every source of external state must be explicitly declared, gated by policy, and logged in the evidence bundle. The pure .ax computation in between is deterministic by construction.

This makes it possible to:

• Reproduce any workflow execution exactly from its evidence bundle
• Prove that a recorded run matches a given workflow definition
• Detect if model behavior has drifted between runs
• Satisfy audit requirements without manual log correlation

The determinism boundary

Boruna draws a hard boundary between pure computation and effects.

Pure (deterministic):

• All .ax expressions and functions
• Record and enum operations
• Pattern matching, conditionals, loops
• Function calls (including recursive)
• Actor message passing (scheduling order is recorded)

Effects (non-deterministic, capability-gated):

• Network requests (net.fetch)
• LLM calls (llm.call)
• Time reads (time.now)
• File system access (fs.read, fs.write)
• Database queries (db.query)
• Random number generation (random)

Effects are declared on functions using capability annotations:

fn fetch_data(url: String) -> String !{net.fetch} {
    // implementation (live mode)
}

Without the !{net.fetch} annotation, a function cannot perform network I/O — the VM enforces this at the bytecode level.

How the EventLog works

Every capability call is intercepted by the CapabilityGateway and written to the EventLog as a CapCall/CapResult pair:

CapCall  { capability: "net.fetch", args: ["https://api.example.com/data"] }
CapResult{ capability: "net.fetch", value: "{\"status\": 200, ...}" }

The EventLog also captures actor lifecycle events (ActorSpawn, MessageSend, MessageReceive, SchedulerTick) so multi-actor scheduling is fully reproducible.

When --record is passed to workflow run, the EventLog is written into the evidence bundle.

Replay verification

Replay works by substituting recorded CapResult values instead of making real calls:

1. Record: Run the workflow with live capabilities. Save the EventLog.
2. Replay: Run the same bytecode. When a CapCall is encountered, return the recorded result instead of executing the effect.
3. Verify: The CapCall sequence must match exactly — same capability, same arguments, same order.

If verification fails, either the workflow is non-deterministic (a bug) or an external value leaked into the pure core.

# Run and record
boruna workflow run examples/workflows/llm_code_review --policy allow-all --record

# Verify the evidence bundle
boruna evidence verify .boruna/runs/<run-id>/

BTreeMap, not HashMap

One concrete implication of the determinism guarantee: all ordered iteration in Boruna’s Rust implementation uses BTreeMap (sorted by key) rather than HashMap (random iteration order). This ensures that serialized outputs and logged values are identical across runs and platforms.

When writing .ax code, Map literals also use deterministic ordering.

Determinism boundaries and guarantees

Not guaranteed:

• LLM output reproducibility (LLMs are probabilistic; Boruna records responses but cannot force models to repeat them)
• Wall-clock timing of individual steps
• External service behavior between record and replay

See also: Limitations, Evidence Bundles

Edit this page on GitHub

Capabilities

A capability is an explicit permission for a workflow step to perform a side effect. No capability, no side effect — the VM enforces this unconditionally.

The eleven capabilities

The 1.0 capability set is frozen in crates/llmbc/src/capability.rs::Capability::ALL. A capability_set_hash, derived from the (name, version) tuples of this set, gives the capability surface a stable identity — reported by the boruna_capability_list MCP tool for compatibility checks.

Declaring capabilities

Capabilities are declared on functions using the !{...} annotation:

fn call_model(prompt: String) -> String !{llm.call} {
    // live mode: calls LLM
}

fn fetch_and_parse(url: String) -> String !{net.fetch} {
    // live mode: makes HTTP request
}

A function without a capability annotation is pure — it cannot perform I/O and its output depends only on its inputs.

Policies

A policy is a set of allowed capabilities. It is specified at runtime, not in the workflow definition. This separation means the same workflow can run in restricted mode during testing and with full capabilities in production.

Built-in policies:

Pass a policy on the CLI:

boruna workflow run my-workflow/ --policy allow-all

In demo mode (no --live flag), capability calls are stubbed or skipped. In live mode, the policy is enforced against every capability call.

Capability enforcement in the VM

Every capability call in compiled bytecode goes through the CapabilityGateway:

1. The VM encounters a capability opcode.
2. The gateway checks the active policy.
3. If the capability is not allowed, the VM returns a CapabilityDenied error immediately.
4. If allowed, the call is dispatched to the registered handler (real HTTP, LLM client, etc.).
5. The call and its result are written to the EventLog.

This enforcement happens at the bytecode level, before any handler executes. There is no way to bypass it from .ax code.

Capabilities in workflow definitions

Workflow steps declare their required capabilities in workflow.json. This makes the capability surface area visible before execution:

{
  "steps": [
    {
      "id": "analyze",
      "source": "steps/analyze.ax",
      "capabilities": ["llm.call"]
    }
  ]
}

The workflow validator checks that declared capabilities are consistent with the policy before the workflow runs.

Capabilities in package manifests

Standard libraries that require capabilities declare them in package.ax.json:

{
  "name": "std-http",
  "capabilities_required": ["net.fetch"]
}

This gives visibility into the transitive capability requirements of a dependency graph.

See also: Determinism, Policies

Edit this page on GitHub

Evidence Bundles

An evidence bundle is the tamper-evident record of a workflow execution. It contains everything needed to prove what ran, when it ran, what inputs were used, what capabilities were invoked, and what outputs were produced.

Evidence bundles are the mechanism through which Boruna supports compliance, audit, and replay.

What an evidence bundle contains

.boruna/runs/<run-id>/
├── manifest.json          # Run metadata: workflow ID, start time, policy, step list
├── audit_log.json         # Hash-chained log of every step execution
├── events/
│   └── event_log.json     # Full CapCall/CapResult/actor event stream
├── steps/
│   ├── <step-id>.input    # Step input values (serialized)
│   └── <step-id>.output   # Step output values (serialized)
└── env_fingerprint.json   # Runtime environment: OS, Boruna version, hash of workflow def

Hash-chained audit log

The audit log is hash-chained: each entry includes the SHA-256 hash of the previous entry. This makes it impossible to insert, delete, or modify a log entry without breaking the chain.

Each log entry records:

• Step ID and source file hash
• Start time and end time
• Policy in effect
• Capability calls made
• Output value hash
• Previous entry hash

The chain starts with a genesis entry that includes the workflow definition hash and the environment fingerprint.

Generating a bundle

Pass --record to workflow run:

boruna workflow run examples/workflows/llm_code_review \
  --policy allow-all \
  --record

# Output:
# Bundle written to: .boruna/runs/20260315-143022-abc4d/

Inspecting a bundle

# Summary view
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/

# Full JSON output
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/ --json

Example output:

Run ID:     20260315-143022-abc4d
Workflow:   llm_code_review
Started:    2026-03-15T14:30:22Z
Completed:  2026-03-15T14:30:31Z
Policy:     allow-all
Steps:      3 completed, 0 failed

Step Results:
  fetch_diff   → ok  (0.1s)
  analyze      → ok  (6.8s)  [llm.call: 1 invocation, 312 tokens]
  report       → ok  (0.0s)

Chain:      valid (3 entries, no gaps)

Verifying a bundle

boruna evidence verify .boruna/runs/20260315-143022-abc4d/

# Output:
# Chain integrity: VALID
# All step hashes: MATCH
# Environment fingerprint: PRESENT
# Verification: PASSED

Verification checks:

1. Hash chain is unbroken from genesis to final entry
2. Step output hashes match recorded values
3. Workflow definition hash matches the definition on disk
4. Environment fingerprint is present and well-formed

A failed verification means either the bundle was tampered with, or the workflow definition changed since the run.

Replaying from a bundle

The evidence bundle contains everything needed to re-execute the workflow with the same capability responses:

boruna workflow run examples/workflows/llm_code_review \
  --replay .boruna/runs/20260315-143022-abc4d/ \
  --verify

In replay mode, LLM calls, HTTP requests, and all other effects return their recorded responses instead of hitting real services. The --verify flag checks that the replayed execution produces the same output hashes.

Compliance relevance

Evidence bundles address several audit requirements directly:

• What ran: Workflow definition hash is recorded
• What model was called: LLM capability calls logged with model identifier
• What the model returned: CapResult entries preserve full responses
• Who approved it: Approval gate decisions are logged as step transitions
• Was it tampered with: Hash chain verification detects any modification

For regulated workflows (financial, healthcare, legal), evidence bundles can be exported and stored in a document management system alongside the artifacts they describe.

See also: Replay, Compliance

Edit this page on GitHub

Evidence Bundle Threat Model

This document states, honestly and without marketing, what an evidence bundle proves and — just as important — what it does not prove. It is written in the SLSA spirit: enumerate the threats, name the concrete mitigation, and name the residual gap that remains after the mitigation.

If you take one sentence away, take this:

An evidence bundle lets you prove that the record was not altered after it was sealed, and that the record is internally consistent under replay. It does not, and cannot, prove that the record was true when it was written.

Everything below is an elaboration of that single distinction.

1. Three properties people conflate

Compliance conversations routinely blur three different guarantees. Boruna delivers the first, delivers the second only under stated conditions, and deliberately does not claim the third.

Keep these separate. Most overclaiming comes from quietly upgrading “tamper-evident” to “tamper-proof”, or from treating a signature as proof of truth rather than proof of origin.

2. What a bundle actually contains

A sealed bundle (orchestrator/src/audit/evidence.rs, BundleManifest) carries, at minimum:

• run_id, workflow_name, workflow_hash, policy_hash
• audit_log_hash — the head of a hash-chained event log
• file_checksums — SHA-256 of every component file (workflow, policy, audit log, env fingerprint, per-step outputs, and optional intents.json / model_invoking_steps.json)
• env_fingerprint — OS / arch / Boruna version, self-reported
• bundle_hash — SHA-256 over the manifest itself (excluding bundle_hash and signature), which therefore commits to every file_checksums entry and the audit_log_hash
• optional encryption — AES-256-GCM envelope metadata
• optional signature — an ed25519 signature over bundle_hash

The integrity contract enforced by verify_bundle (orchestrator/src/audit/verify.rs): every file’s on-disk SHA-256 must match file_checksums; the audit-log chain must be unbroken (entry_hash = SHA-256(prev_hash || event_json)); the chain head must equal audit_log_hash; and all required components must be present. For the full on-disk contract see Evidence Bundles and the format spec at docs/spec/evidence-bundle-1.0.md.

3. Threats and mitigations

4. Why “detects tampering” needs a footnote

Plain boruna evidence verify gives you internal consistency: it recomputes every checksum and the chain and confirms they agree with the manifest. That catches accidental corruption and unsophisticated edits.

It does not, by itself, catch an attacker who controls the whole bundle, because that attacker can make the manifest agree with their forgery. Two independent, composable checks close this gap; neither is on by default, and each roots trust in something the attacker does not control:

1. External anchor (--expected-bundle-hash / expected_bundle_hash). You record the bundle_hash out-of-band at seal time — in a separate system the attacker cannot rewrite — and supply it at verify time. Verification then requires the recomputed hash to equal your anchor, not the manifest’s self-reported one. A forged-but-self-consistent bundle fails because its recomputed hash no longer matches the anchor you kept. This is what makes a plaintext bundle genuinely tamper-evident against a motivated attacker.

2. ed25519 signature under a pinned key (--verify-key / trusted_pubkey, optionally require_signature). The producer signs bundle_hash with an ed25519 key; the verifier pins the expected public key. Trust is rooted in the pinned key: a bundle re-signed with any other key is rejected as signature_untrusted_key. Without pinning, a signature proves only that some key signed — an attacker can substitute their own.

The signature’s meaning is precise: it attests which key sealed these bytes. That is an origin/authenticity claim about the producer, not a truth claim about the content (contrast the malicious-producer row in §3). Non-repudiation follows only to the extent that the key is bound to an accountable identity and is not shared — conditions the bundle format cannot enforce on its own.

5. Mitigation directions (not yet implemented)

The residual gaps in §3 are real. The honest position is that they are known and have known remedies on the roadmap, none of which ship today:

• Transparency-log anchoring (Rekor-style): witness the bundle_hash in an external append-only log at seal time, giving a third-party- attested earliest-existence timestamp and defeating silent backdating.
• Keyless / identity-bound signing: bind a signature to a verifiable workload identity for a short-lived credential, reducing the blast radius of a stolen long-lived key.
• TEE remote attestation: replace the self-reported environment fingerprint with a hardware-attested measurement of the code image and platform that actually executed.

Until these land, treat the corresponding claims conservatively: a bundle proves post-seal integrity and internal replay-consistency, anchored or signed bundles additionally prove origin against a chosen root of trust, and nothing in the bundle proves the producer was honest or that the timestamps are true.

6. See also

• Evidence Bundles — on-disk layout, hash chain, and the verify / inspect / replay workflow.
• Runtime Execution Provenance — the provenance category Boruna occupies, and how it relates to SLSA, in-toto, Sigstore, C2PA, and TEE attestation.
• docs/spec/evidence-bundle-1.0.md — the normative format and integrity contract.

Edit this page on GitHub

Runtime Execution Provenance

Boruna occupies a provenance category that the established supply-chain and content-authenticity standards leave largely unoccupied: runtime execution provenance — an attested, tamper-evident record of what a specific execution actually did.

The claim this category makes is narrow and concrete:

This specific run executed these steps, made these policy-gated capability calls, under this policy, transforming these recorded inputs into these recorded outputs.

That is a statement about an execution trace, not about a build, an artifact, a signing event, a media file, or a booted code image. The distinction matters because the standards people reach for by reflex all answer a different question.

1. The provenance landscape

Each of these standards is good at what it targets. None of them targets the execution trace of a particular run.

Read down the right-hand column: build provenance, supply-chain step metadata, signing events, content lineage, and code identity are all covered — and the runtime execution trace falls through the gap between them. Boruna’s evidence bundle is aimed squarely at that gap.

These standards are complementary, not competitors. A mature deployment might use SLSA for the binary, TEE attestation for the platform, and Boruna for the execution trace — each answering the question it is built to answer.

2. What Boruna attests

The evidence bundle records the run itself. The load-bearing components (see Evidence Bundles and orchestrator/src/audit/evidence.rs) map directly onto the category claim:

• These steps executed — the hash-chained audit_log, whose entries record step start/completion and capability calls in order, with each entry chained to the previous (entry_hash = SHA-256(prev_hash || event_json)).
• Under this policy — policy.json and its policy_hash; the policy snapshot that gated the run is sealed alongside the trace, so a verifier sees the exact rules in force.
• Made these gated capability calls — capability calls appear in the audit log / event stream; the optional model_invoking_steps.json additionally records which steps transitively reached an LLM capability, so an auditor can see which steps touched a model without re-analyzing sources.
• Transforming these inputs into these outputs — per-step outputs under outputs/<step>/<name>.json, each SHA-256-checksummed in file_checksums and thereby committed to by bundle_hash.
• With declared purpose — the optional intents.json records the per-step declared intent (what each step was authorized to do), captured as replay-verified evidence alongside what it actually did.

All of these are covered by the same integrity contract: on-disk checksums, an unbroken audit-log chain, and a bundle_hash over the manifest. The record is therefore tamper-evident in exactly the sense defined in the Evidence Bundle Threat Model — and, as that document is careful to state, tamper-evidence is not tamper-proofing, and a sealed trace attests what was recorded, not that the producer recorded honestly.

3. Interoperability with the standards

Occupying a distinct category does not mean living apart from the ecosystem. The intent is for a Boruna execution record to slot into existing supply-chain and attestation tooling rather than replace it.

To that end, an in-toto / DSSE emission is available via boruna evidence attest <bundle-dir>: it exports the bundle’s core attestation (run identity, workflow_hash, policy_hash, audit_log_hash, output digests) as an in-toto Statement (predicateType: https://boruna.dev/runtime-provenance/v1) wrapped in a DSSE envelope signed with the bundle’s ed25519 key. That makes the execution-provenance claim consumable by the same tooling that already ingests SLSA and in-toto attestations — for example, a transparency log or a policy engine that gates on attestations. The predicate schema is specified in docs/spec/runtime-provenance-predicate-1.0.md.

Status note. The in-toto/DSSE emitter is implemented (boruna evidence attest, --verify to check the envelope). It is additive — the native, authoritative format remains the evidence bundle described in docs/spec/evidence-bundle-1.0.md. Live interoperability with a specific cosign/in-toto-verify binary is spec-conformant but not yet end-to-end verified (the DSSE keyid is a raw-hex ed25519 key that a consumer must bridge to PEM SPKI); see the predicate spec’s compatibility notes.

The relationship is layered, not overlapping:

• SLSA / in-toto attest how the software (and, via DSSE, other attestations) was produced and assembled.
• Sigstore / Rekor can witness signatures — including, once emitted, a DSSE-wrapped Boruna attestation — in an append-only log.
• TEE attestation can vouch for the platform and code image that ran the Boruna engine.
• Boruna attests the execution trace that happened on top of all of the above.

Each layer roots a different claim; together they compose into a story that no single standard tells alone.

4. See also

• Evidence Bundles — the concrete artifact that carries the execution-provenance record.
• Evidence Bundle Threat Model — precisely what the record proves and does not prove (tamper-evidence vs. tamper-proofing vs. non-repudiation).
• docs/spec/evidence-bundle-1.0.md — the normative on-disk format and integrity contract.

Edit this page on GitHub

Bundle Storage

Evidence bundles are written to local disk by the orchestrator (see Evidence Bundles). The Bundle Storage layer is an optional second-stage that copies the finalized bundle to a durable remote backend after the local write succeeds.

The local bundle is always the authoritative record. Remote storage is additive durability — operators choose to enable it for compliance, archival, or cross-region disaster recovery.

Backends

All four schemes share the same trait, the same dispatcher, and the same failure contract — everything below applies to every backend.

How it works

Pass the URI to boruna workflow run --record:

boruna workflow run my-workflow \
  --policy allow-all \
  --record \
  --bundle-storage s3://my-audit-bucket/prod

After the run finalizes locally, the orchestrator:

1. Resolves the URI to a BundleStorage adapter via from_uri.
2. Calls storage.put(run_id, bundle_dir).
3. Records the returned StorageRef in the run output as storage_ref.

The BORUNA_BUNDLE_STORAGE env var is the standard way to set this once for an entire deployment.

Failure contract

A storage failure never masks a successful workflow.

If the remote backend is unreachable, returns auth errors, or hits any other backend failure:

• The orchestrator logs a warning to stderr.
• The local bundle remains on disk and remains the authoritative record.
• The workflow exits successfully (the remote copy is not required for the run to be considered complete).
• storage_ref is omitted from the output.

Operators who require remote durability should monitor the warning output and re-run evidence verify against the local bundle to confirm it is still on disk before pruning it.

Reading bundles back

Once you have a storage_ref, materialize the bundle into a local cache directory:

#![allow(unused)]
fn main() {
use boruna_orchestrator::audit::storage::{from_uri, StorageRef};

let storage = from_uri(Some("s3://my-audit-bucket/prod"))?.unwrap();
let local_dir = storage.get(&StorageRef("s3://my-audit-bucket/prod/<run-id>".into()))?;
boruna_orchestrator::audit::verify_bundle(&local_dir)?;
}

The cache directory defaults to <temp>/boruna-bundle-cache and is overridable via BORUNA_BUNDLE_CACHE. It is shared across all remote adapters; if you operate multi-cloud and care about cross-bucket consistency, set per-bucket cache directories yourself.

OFF-feature behavior

When you build the binary without the feature for a remote scheme, the corresponding URI rejects at parse time with an actionable message that points at the feature flag:

$ boruna workflow run --bundle-storage s3://b/p ...
warning: --bundle-storage URI invalid: s3://b/p requires the `s3` feature; rebuild with `--features boruna-cli/s3`

This is a deliberate design choice: silently ignoring the URI would create an audit gap (the operator believes their bundle is going to S3 but it is not). The warning is loud, the build directive is explicit, and the workflow still completes successfully against local storage.

Determinism contract

The storage_ref returned by put is operational metadata — it does not feed any audit-log hash or replay comparison. The bundle’s bundle_hash and audit_log_hash are computed from the local manifest before remote upload begins; where the bundle is also stored does not affect those hashes.

This means: a bundle uploaded to S3 yesterday and to GCS today carries the same bundle_hash. The two storage_refs differ; the underlying audit content is identical.

Stable error taxonomy

BundleStorage::put / get / list return StorageError. The Backend { kind, msg } variant carries a stable per-adapter kind string so integrators can branch on retry semantics:

StorageError is #[non_exhaustive], so adding a new variant in a future release is additive (existing match arms keep compiling). Likewise, new kind strings are additive — integrators switching on kind should treat unknown values as transient (retryable) by default.

See also

• Evidence Bundles — what’s inside a bundle and how the audit chain works
• The per-adapter operator guides linked in the table above
• API reference: boruna_orchestrator::audit::storage — the trait, dispatcher, and LocalFs adapter
• API reference: boruna_orchestrator::audit::storage_{s3,gcs,azure} — the per-provider implementations (each behind its own feature flag)

Edit this page on GitHub

Compliance Evidence

Evidence Bundles

Every workflow run with --record produces a self-contained evidence bundle — a directory of artifacts sufficient for compliance audit.

Bundle Contents

Manifest Fields

{
  "schema_version": 1,
  "run_id": "run-my-workflow-20260221T120000",
  "workflow_name": "my-workflow",
  "workflow_hash": "<sha256>",
  "policy_hash": "<sha256>",
  "audit_log_hash": "<sha256>",
  "file_checksums": {
    "workflow.json": "<sha256>",
    "policy.json": "<sha256>",
    "audit_log.json": "<sha256>"
  },
  "env_fingerprint": {
    "boruna_version": "0.1.0",
    "rust_version": "...",
    "os": "linux",
    "arch": "x86_64",
    "hostname": "worker-01"
  },
  "started_at": "2026-02-21T12:00:00Z",
  "completed_at": "2026-02-21T12:00:01Z",
  "bundle_hash": "<sha256>"
}

Verification

boruna evidence verify <bundle-dir>

Verification checks:

1. All files listed in file_checksums exist and match their SHA-256 hashes
2. Audit log hash-chain is intact (each entry’s hash includes the previous)
3. Audit log hash matches the manifest’s audit_log_hash
4. Required files are present (manifest, workflow, policy, audit log, fingerprint)

Audit Log

The audit log is a JSON array of hash-chained entries:

[
  {
    "sequence": 0,
    "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000",
    "event": { "WorkflowStarted": { "workflow_hash": "...", "policy_hash": "..." } },
    "entry_hash": "<sha256>"
  },
  {
    "sequence": 1,
    "prev_hash": "<hash of entry 0>",
    "event": { "StepCompleted": { "step_id": "fetch", "output_hash": "...", "duration_ms": 42 } },
    "entry_hash": "<sha256>"
  }
]

Tamper Detection

Each entry’s hash = SHA-256(sequence + prev_hash + event_json). Modifying any entry invalidates all subsequent hashes.

Determinism Proof

To prove determinism:

1. Run the same workflow twice with --record
2. Compare evidence bundles: file checksums should be identical (excluding timestamps)
3. Audit log event hashes should match for the same events

What This Proves

For compliance auditors, an evidence bundle demonstrates:

• What ran: Exact workflow definition and policy
• When it ran: Timestamps and run ID
• Where it ran: Environment fingerprint
• What happened: Complete audit trail of every step, decision, and output
• Integrity: SHA-256 hash chain prevents undetected modification

Edit this page on GitHub

LLM Integration Guide

Boruna does not ship a default LLM handler. The supported integration model is Bring Your Own Handler (BYOH) — you implement the CapabilityHandler trait against your provider of choice, and pass the handler into CapabilityGateway::with_handler at workflow run time.

This document explains why, what the contract looks like, and how to wire up handlers for common providers (OpenAI, Anthropic, vLLM, Ollama).

Why BYOH?

Three reasons.

1. Provider churn doesn’t destabilize Boruna. OpenAI’s API changes; so does Anthropic’s; so does the long tail. If a default handler shipped in core, every provider release would risk a Boruna patch release. With BYOH, your handler tracks your provider on your release cadence.

2. API key management belongs in your application. Boruna is a deterministic execution chassis. Secret loading, rotation, observability, billing attribution — all of these are concerns that vary wildly per organization. Pushing them into core would constrain integrators (e.g. FleetQ) who already have their own conventions.

3. Most production integrators already have an LLM client. The platform’s primary integrators run their own LLM infrastructure (vLLM clusters, OpenRouter proxies, custom routing). Shipping a default handler would just add another thing for them to override.

A “convenience CLI handler” was considered and rejected — it would lock the project into provider compatibility commitments without serving the production integrators it’s primarily meant for.

The contract

CapabilityHandler is a single-method trait in boruna-vm::capability_gateway:

#![allow(unused)]
fn main() {
pub trait CapabilityHandler: Send {
    fn handle(&mut self, cap: &Capability, args: &[Value]) -> Result<Value, String>;
}
}

For LLM calls, the relevant capability is Capability::LlmCall. The first argument is conventionally the prompt (a Value::String); subsequent arguments are provider-specific. The return is the LLM’s response, also conventionally Value::String or Value::Map { "content": ..., "finish_reason": ... }.

The handler runs inside the VM’s step execution. It has Send bound but no Sync — each VM instance owns its own handler. In the concurrent execution path (--concurrency > 1), each worker constructs its own handler.

Minimal example

#![allow(unused)]
fn main() {
use boruna_bytecode::{Capability, Value};
use boruna_vm::capability_gateway::CapabilityHandler;

pub struct OpenAiHandler {
    api_key: String,
    client: ureq::Agent,
}

impl OpenAiHandler {
    pub fn from_env() -> Result<Self, String> {
        let api_key = std::env::var("OPENAI_API_KEY")
            .map_err(|_| "OPENAI_API_KEY not set".to_string())?;
        Ok(Self {
            api_key,
            client: ureq::AgentBuilder::new()
                .timeout(std::time::Duration::from_secs(60))
                .build(),
        })
    }
}

impl CapabilityHandler for OpenAiHandler {
    fn handle(&mut self, cap: &Capability, args: &[Value]) -> Result<Value, String> {
        match cap {
            Capability::LlmCall => self.handle_llm_call(args),
            // Delegate everything else to the default mock handler.
            _ => boruna_vm::capability_gateway::MockHandler.handle(cap, args),
        }
    }
}

impl OpenAiHandler {
    fn handle_llm_call(&mut self, args: &[Value]) -> Result<Value, String> {
        let prompt = args
            .first()
            .and_then(|v| match v {
                Value::String(s) => Some(s.as_str()),
                _ => None,
            })
            .ok_or_else(|| "llm.call: first arg must be a String prompt".to_string())?;

        let body = serde_json::json!({
            "model": "gpt-4o-mini",
            "messages": [{"role": "user", "content": prompt}],
        });

        let resp = self
            .client
            .post("https://api.openai.com/v1/chat/completions")
            .set("Authorization", &format!("Bearer {}", self.api_key))
            .set("Content-Type", "application/json")
            .send_json(body)
            .map_err(|e| format!("openai request failed: {e}"))?;

        let json: serde_json::Value = resp
            .into_json()
            .map_err(|e| format!("openai response parse: {e}"))?;
        let content = json
            .get("choices")
            .and_then(|c| c.get(0))
            .and_then(|c| c.get("message"))
            .and_then(|m| m.get("content"))
            .and_then(|c| c.as_str())
            .ok_or_else(|| "openai response missing choices[0].message.content".to_string())?;

        Ok(Value::String(content.to_string()))
    }
}
}

A complete reference handler lives in examples/llm_handlers/openai/. The directory contains handler.rs (a self-contained module you can copy into your integrator crate) and a README documenting the per-provider gotchas.

Provider variants

Reference handlers ship for the most common providers (post1-T-1.2). Each is a copy-and-tweak template, not a compiled crate Boruna pulls in:

The umbrella examples/llm_handlers/README.md gives the cross-provider overview and links each handler’s gotchas (auth header, response path, determinism options).

A documented providers.toml.example schema and a router_setup.rs reference parser show one convention for declaring your provider lineup in config rather than code. The format is a starting point — Boruna does not parse it.

For multi-provider routing, use the built-in LlmRouterHandler (covered next), or have your handler switch on a model argument (passed as args[1]) or on a thread-local context.

LlmRouterHandler — built-in multi-provider dispatch (sprint 0.4-S13)

If you have multiple providers wired in (OpenAI + Anthropic + a local Ollama, say) and don’t want to write your own dispatch logic, Boruna ships a LlmRouterHandler in boruna-vm::capability_gateway. It takes a registry of provider handlers keyed by name and dispatches each Capability::LlmCall based on a provider/model prefix in args[1]:

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;
use boruna_vm::capability_gateway::{
    CapabilityHandler, LlmRouterHandler, MockHandler,
};

let mut providers: BTreeMap<String, Box<dyn CapabilityHandler>> = BTreeMap::new();
providers.insert("openai".into(), Box::new(my_openai_handler));
providers.insert("anthropic".into(), Box::new(my_anthropic_handler));
providers.insert("ollama".into(), Box::new(my_ollama_handler));

// Non-LLM calls pass through to the fallback (typically MockHandler
// in tests; in production you'd plug a HttpHandler etc).
let router = LlmRouterHandler::new(providers, Box::new(MockHandler));

// Pass `router` into `CapabilityGateway::with_handler` like any
// other CapabilityHandler.
}

.ax callers then write:

let response = llm_call("Summarize:", "openai/gpt-4")
let response2 = llm_call("Translate:", "anthropic/claude-3-5-sonnet-20241022")

The full model string (including the provider/ prefix) is forwarded to the provider’s handler unchanged, so providers can use the prefix internally (e.g. for billing tags).

The router does not impose provider compatibility commitments on core — it’s pure routing logic. You still bring your own per-provider handler implementation. boruna-vm ships zero provider HTTP code.

Determinism considerations

LLM calls are inherently non-deterministic at the model layer (sampling temperature, randomness, model version drift). Three things keep Boruna’s determinism contract intact even with non-deterministic handlers:

1. output_hash reflects what was actually returned. If the LLM returned different text on two runs, the output_hash differs and downstream replay-comparison surfaces the divergence.
2. net.fetch record-replay (sprint 0.5-S7) lets you record an LLM session and replay deterministically — useful for testing and audit.
3. Persisted output_json (sprint 0.3-S2b) means a successful LLM call’s output survives process restarts. Resume picks up the recorded value rather than re-calling the LLM.

For workflows that need bit-identical replay, set temperature: 0 and a pinned model version, then use --record-net-to to capture the network transactions for future replay.

Capability policy

Steps that call LLMs must declare the capability in the workflow definition:

{
  "steps": {
    "summarize": {
      "kind": "source",
      "source": "steps/summarize.ax",
      "capabilities": ["llm.call"],
      "budget": { "max_calls": 3 }
    }
  }
}

The budget.max_calls field caps how many llm.call invocations the step is allowed. Exceeding the budget returns a CapabilityBudgetExceeded runtime error. Per-step budgeting is enforced by CapabilityGateway regardless of which handler is plugged in.

Testing your handler

Two patterns:

1. Mock at the trait level — pass a stub CapabilityHandler that returns canned responses. Fast, doesn’t hit the network. Use this for the bulk of your test suite.
2. Record + replay — run once with the real handler and --record-net-to <tape>, then in tests run with --replay-net-from <tape>. Captures the actual provider response shape but stays offline. Recommended for integration tests and CI.

Where to look in the code

• crates/llmvm/src/capability_gateway.rs — CapabilityHandler trait + MockHandler (default).
• crates/llm-effect/ — higher-level prompt, cache, context primitives (provider-agnostic).
• examples/llm_handlers/ — reference handler implementations.

What this guide is NOT

• Not a tutorial on prompt engineering. See crates/llm-effect/’s prompt module for the prompt-building primitives Boruna ships.
• Not a recommendation of a specific provider. Pick what your organization standardizes on.
• Not a streaming-API guide. Boruna’s capability calls are synchronous; streaming responses must be collected to a single value before returning.

Edit this page on GitHub

Model Evaluation Framework

boruna workflow eval runs the same workflow against two LLM provider configurations and compares the resulting evidence bundles.

Usage

boruna workflow eval examples/workflows/llm_code_review \
  --providers-a anthropic.json \
  --providers-b ollama.json \
  --runs 3

Provider config format

{
  "llm.call": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "api_key_env": "ANTHROPIC_API_KEY"
  }
}

Supported providers: anthropic, ollama, openai_compat, deny, passthrough.

See docs/guides/llm-integration.md for full BYOH handler wiring.

Output

The command prints a comparison table:

Provider A (anthropic): 3/3 runs succeeded (100%), mean 1420ms
Provider B (ollama):    3/3 runs succeeded (100%), mean 890ms

Step                     A identical   B identical   A vs B agree
----------------------------------------------------------------------
analyze                  yes           yes           no  (different)
report                   yes           yes           yes (identical)

Use --json for machine-readable output suitable for CI pipelines.

Options

Evidence bundles

Each run writes a full evidence bundle under <data-dir>/model-eval/<provider-name>/run_N/evidence/. These can be inspected with boruna evidence inspect or diffed with boruna evidence diff.

Notes on live LLM comparison

The eval command validates the config and logs the provider that would be used, then runs the workflow in demo mode. Live provider comparison (actual LLM API calls) requires the boruna-vm/http feature and wired BYOH handlers — see docs/guides/llm-integration.md.

Edit this page on GitHub

Testing Guide

TestHarness

The primary testing tool. No host UI required.

#![allow(unused)]
fn main() {
use boruna_framework::testing::TestHarness;
use boruna_framework::runtime::AppMessage;
use boruna_bytecode::Value;

let mut harness = TestHarness::from_source(SOURCE)?;
}

Send Messages

#![allow(unused)]
fn main() {
let (state, effects) = harness.send(
    AppMessage::new("increment", Value::Int(0))
)?;
}

Simulate Sequences

#![allow(unused)]
fn main() {
let final_state = harness.simulate(vec![
    AppMessage::new("add", Value::Int(0)),
    AppMessage::new("add", Value::Int(0)),
    AppMessage::new("complete", Value::Int(0)),
])?;
}

Assertions

#![allow(unused)]
fn main() {
// Check a specific field by index
harness.assert_state_field(0, &Value::Int(3))?;

// Check full state equality
harness.assert_state(&expected_value)?;

// Check effects from last cycle
harness.assert_effects(&["http_request"])?;
}

Snapshots

#![allow(unused)]
fn main() {
let json = harness.snapshot();  // JSON string of current state
}

Time Travel

#![allow(unused)]
fn main() {
harness.rewind(0)?;  // Go back to init state
}

Replay Verification

#![allow(unused)]
fn main() {
let messages = vec![
    AppMessage::new("increment", Value::Int(0)),
    AppMessage::new("increment", Value::Int(0)),
];
for msg in &messages {
    harness.send(msg.clone())?;
}

// Replay same messages on fresh runtime, verify identical states
let identical = harness.replay_verify(SOURCE, messages)?;
assert!(identical);
}

Golden Tests

Golden tests verify determinism. Run the same messages twice, compare:

#![allow(unused)]
fn main() {
let mut h1 = TestHarness::from_source(SOURCE)?;
let mut h2 = TestHarness::from_source(SOURCE)?;

for msg in &messages {
    h1.send(msg.clone())?;
    h2.send(msg.clone())?;
}

assert_eq!(h1.state(), h2.state());
assert_eq!(h1.snapshot(), h2.snapshot());
}

CLI Testing

# Validate app protocol
boruna framework validate my_app.ax

# Send messages and see state
boruna framework test my_app.ax -m "add:0,add:0,complete:0"

# Inspect state as JSON
boruna framework inspect-state my_app.ax -m "add:0,add:0"

# Step-by-step simulation
boruna framework simulate my_app.ax "add:0,add:0,complete:0"

# Machine-readable diagnostics
boruna framework diag my_app.ax -m "add:0,add:0"

# Stable trace hash (for CI comparison)
boruna framework trace-hash my_app.ax -m "add:0,add:0"

# App contract summary
boruna framework inspect my_app.ax --json

Message Format

CLI messages use tag:payload format:

• increment:0 → tag=“increment”, payload=Int(0)
• fetch:https://example.com → tag=“fetch”, payload=String(“https://example.com”)
• reset → tag=“reset”, payload=Int(0) (default)

Comma-separated for sequences: add:0,add:0,complete:0

Writing Test Apps

Include fn main() -> Int for standalone execution:

fn main() -> Int {
    let s0: State = init()
    let r1: UpdateResult = update(s0, Msg { tag: "add", payload: 0 })
    let r2: UpdateResult = update(r1.state, Msg { tag: "add", payload: 0 })
    r2.state.total
}

Run directly: boruna run my_app.ax

Edit this page on GitHub

Trace → Regression Tests + Minimizer

Overview

The trace2tests module converts runtime execution traces into deterministic regression tests. It also provides a delta-debugging minimizer that shrinks failing traces to minimal reproducing sequences.

Trace Schema

Version 1, stable JSON format.

{
  "version": 1,
  "source_file": "path/to/app.ax",
  "source_hash": "sha256:<hex>",
  "cycles": [
    {
      "cycle": 1,
      "message": { "tag": "increment", "payload": {"Int": 0} },
      "state_before_hash": "sha256:<hex>",
      "state_after_hash": "sha256:<hex>",
      "state_after": {"Record": {"type_id": 0, "fields": [{"Int": 1}]}},
      "effects": [
        { "kind": "http_request", "payload_hash": "sha256:<hex>", "callback_tag": "on_response" }
      ],
      "ui_tree_hash": "sha256:<hex>"
    }
  ],
  "final_state_hash": "sha256:<hex>",
  "trace_hash": "sha256:<hex>"
}

Fields

Hashing

All hashes use SHA-256 of canonical JSON serialization:

• Values are serialized via serde (deterministic for BTreeMap)
• The trace fingerprint concatenates all cycle data in stable format
• Same inputs always produce identical hashes

Test Spec Format

Generated test specifications are self-contained JSON:

{
  "version": 1,
  "name": "counter_regression",
  "source_file": "examples/counter.ax",
  "source_hash": "sha256:<hex>",
  "messages": [
    { "tag": "increment", "payload": {"Int": 0} },
    { "tag": "decrement", "payload": {"Int": 0} }
  ],
  "assertions": [
    { "kind": "final_state_hash", "expected": "sha256:<hex>", "description": "..." },
    { "kind": "trace_hash", "expected": "sha256:<hex>", "description": "..." },
    { "kind": "cycle_count", "expected": "2", "description": "..." }
  ]
}

Assertion Kinds

Delta Debugging Minimizer

Implements the ddmin algorithm to shrink failing message sequences:

1. Chunk removal: Split into n chunks, try removing each
2. Granularity increase: If no chunk removal works, try finer splits
3. 1-minimal pass: Try removing each individual message
4. Result is guaranteed 1-minimal (removing any single message stops the failure)

Predicates

Built-in predicates:

• panic: Failure = runtime error during message processing
• State mismatch: Failure = final state hash differs from expected

External predicates: Any command that receives a temp trace file path and returns non-zero on failure.

CLI Usage

Record

boruna trace2tests record <file.ax> --messages "tag:payload,..." --out trace.json

Generate

boruna trace2tests generate --trace trace.json --out test_spec.json [--name test_name]

Run

boruna trace2tests run --spec test_spec.json [--source app.ax]

Minimize

boruna trace2tests minimize --trace trace.json --source app.ax [--predicate panic]
boruna trace2tests minimize --trace trace.json --source app.ax --predicate "my_check.sh"

Determinism Guarantees

• Same source + same messages = identical trace hash
• Generated tests are deterministic regression gates
• Minimizer produces deterministic output (same input → same minimal trace)
• All hashes use SHA-256 with canonical serialization

Integration

• Trace files are compatible with the framework’s CycleRecord format
• Test specs can be version-controlled alongside source
• Minimized traces export as regression tests via generate
• The full pipeline: record → minimize → generate → run

Edit this page on GitHub

App Template

Canonical File Layout

my_app/
  my_app.ax       # Single source file

Minimal App Skeleton

// my_app — Boruna Framework App

type State { value: Int }
type Msg { tag: String, payload: Int }
type Effect { kind: String, payload: String, callback_tag: String }
type UpdateResult { state: State, effects: List<Effect> }
type UINode { tag: String, text: String }

fn init() -> State {
    State { value: 0 }
}

fn update(state: State, msg: Msg) -> UpdateResult {
    UpdateResult {
        state: State { value: state.value + msg.payload },
        effects: [],
    }
}

fn view(state: State) -> UINode {
    UINode { tag: "text", text: "value" }
}

fn main() -> Int {
    let s: State = init()
    s.value
}

Required Types

Required Functions

Optional Functions

Create From CLI

boruna framework new my_app
boruna framework validate my_app/my_app.ax
boruna run my_app/my_app.ax

Policy Template

type PolicySet { capabilities: List<String>, max_effects: Int, max_steps: Int }

fn policies() -> PolicySet {
    PolicySet {
        capabilities: ["net.fetch", "time.now"],
        max_effects: 10,
        max_steps: 1000000,
    }
}

Edit this page on GitHub

Effects Guide

Overview

Effects are declarative descriptions of side effects. update() never performs IO directly. Instead, it returns a list of effects. The framework runtime executes them via the capability gateway.

Effect Structure

type Effect { kind: String, payload: String, callback_tag: String }

• kind — which effect to execute (see table below)
• payload — data for the effect (URL, query, path, etc.)
• callback_tag — message tag for the result delivery

Built-in Effect Kinds

Returning Effects From update()

fn update(state: State, msg: Msg) -> UpdateResult {
    if msg.tag == "fetch" {
        UpdateResult {
            state: state,
            effects: [
                Effect {
                    kind: "http_request",
                    payload: "https://api.example.com/data",
                    callback_tag: "data_received",
                },
            ],
        }
    } else {
        UpdateResult { state: state, effects: [] }
    }
}

Effect Lifecycle

1. update() returns UpdateResult { state, effects }.
2. Framework validates effects against the policy.
3. Framework (or host) executes each effect via capability gateway.
4. Effect results are delivered as new messages with callback_tag as the tag.
5. update() handles the callback message in the next cycle.

Multiple Effects Per Cycle

Return multiple effects in the list. They execute in order.

effects: [
    Effect { kind: "http_request", payload: "url1", callback_tag: "result" },
    Effect { kind: "http_request", payload: "url2", callback_tag: "result" },
    Effect { kind: "http_request", payload: "url3", callback_tag: "result" },
]

Policy Constraints

Effects are checked against the app’s PolicySet:

• Only listed capabilities are allowed.
• max_effects_per_cycle limits how many effects per update.
• Violations produce FrameworkError::PolicyViolation.

Determinism

Effects themselves are deterministic data. Their execution results are logged by the capability gateway. Replay substitutes recorded results, making the entire execution deterministic.

Edit this page on GitHub

Actors Guide

Status

Actor integration in the framework is partial. The VM has an ActorSystem with basic spawn/send/receive mechanics. The framework does not yet wire actors into the App protocol runtime.

Architecture

Parent App
  ├── init() → State
  ├── update(state, msg) → UpdateResult
  │     └── effects: [Effect { kind: "spawn_actor", ... }]
  ├── view(state) → UINode
  └── Child Actor (same App protocol)
        ├── init() → State
        ├── update(state, msg) → UpdateResult
        └── view(state) → UINode

Spawning Actors

Return a spawn_actor effect from update():

Effect { kind: "spawn_actor", payload: "child_module", callback_tag: "child_spawned" }

The framework runtime will:

1. Compile and initialize the child module.
2. Assign it an actor ID.
3. Deliver a child_spawned message to the parent with the actor ID.

Message Routing

Messages between actors use the tag routing convention:

• Parent → Child: effect with kind: "send_to_actor" (not yet implemented)
• Child → Parent: effect with kind: "emit_ui" or framework routing

Supervision

If a child actor crashes (runtime error), the parent receives an error message:

• Tag: "actor_error"
• Payload: error description

Scheduling

In single-actor mode: FIFO message processing, deterministic. In multi-actor mode: round-robin scheduling, deterministic order in debug mode.

Current Limitations

1. Actor spawning is not executed by the framework runtime (only parsed as effects).
2. No inter-actor message routing at the framework level.
3. No supervision tree implementation.
4. The VM’s ActorSystem exists but is not integrated with AppRuntime.

VM-Level Actor API

The VM provides these opcodes for actors:

• SpawnActor(func_idx) — spawn actor from function
• SendMsg — send message to actor ID
• ReceiveMsg — block for incoming message

These are available in bytecode but not yet connected to the framework’s effect-based actor model.

Edit this page on GitHub

Operations Guide

Running Workflows

Validate

boruna workflow validate <workflow-dir>

Checks DAG structure, step references, input/output wiring, and cycle detection.

Run

boruna workflow run <workflow-dir> --policy allow-all
boruna workflow run <workflow-dir> --policy deny-all
boruna workflow run <workflow-dir> --policy path/to/policy.json

Run with Evidence Recording

boruna workflow run <workflow-dir> --policy allow-all --record
boruna workflow run <workflow-dir> --record --evidence-dir ./evidence

Produces an evidence bundle directory containing:

• manifest.json — bundle metadata with checksums
• workflow.json — workflow definition snapshot
• policy.json — policy snapshot
• audit_log.json — hash-chained audit entries
• env_fingerprint.json — runtime environment info
• outputs/<step_id>/result.json — per-step output data

Verifying Evidence

boruna evidence verify <bundle-dir>

Checks:

• File checksums match manifest
• Audit log chain integrity
• Required files present

boruna evidence inspect <bundle-dir>
boruna evidence inspect <bundle-dir> --json

Displays bundle manifest details.

Replay

For single-file execution:

boruna run app.ax --record trace.json
boruna replay app.axbc trace.json

For workflow-level replay, re-run the workflow in mock mode using recorded outputs.

Observability

Current

• CLI output shows per-step status, duration, and errors
• Evidence bundles capture all execution details
• Audit log provides ordered event history

Planned (Gap)

• Structured JSON logging via tracing crate
• Metrics (latency per step, cache hit rate, budget consumption)
• OpenTelemetry trace export

CI Integration

# Validate all example workflows
for dir in examples/workflows/*/; do
  boruna workflow validate "$dir"
done

# Run in mock mode and verify
boruna workflow run examples/workflows/llm_code_review --record
boruna evidence verify examples/workflows/llm_code_review/evidence/<run-id>

Deployment

Boruna is a statically-linked Rust binary. Deploy by copying the binary to the target system.

cargo build --release --bin boruna
# Binary at: target/release/boruna

Daemon/service mode is documented as a P2 gap in ENTERPRISE_GAPS.md.

Edit this page on GitHub

Language Server (LSP) Setup

boruna-lsp implements the Language Server Protocol for .ax files.

Build

cargo build --bin boruna-lsp

VS Code

Install the official LSP client extension (coming soon), or configure manually in .vscode/settings.json:

{
  "boruna.lsp.serverPath": "/path/to/boruna-lsp"
}

Or use the generic vscode-languageclient setup with any LSP-capable extension.

Neovim (nvim-lspconfig)

require('lspconfig').boruna_lsp.setup {
  cmd = { '/path/to/boruna-lsp' },
  filetypes = { 'ax' },
  root_dir = require('lspconfig.util').root_pattern('Cargo.toml', '.git'),
}

Features

Edit this page on GitHub

Migration tooling (beta)

Status: beta (sprint W5-C). API and on-disk shapes may shift in the 0.6 line; the public CLI invocation will remain stable.

boruna migrate upgrades pre-1.0 artifacts to the format the current release expects. It is the supported way to bring legacy evidence bundles and workflow definitions forward as Boruna’s on-disk contracts evolve toward 1.0.

When to use it

If you are starting fresh with 0.6.0+, you do not need this tool — new artifacts are produced in the current format.

CLI shape

boruna migrate <kind> <path> [--from <version>] [--to <version>] [--dry-run] [--in-place]

Recommended workflow

Always do this before shipping a migrated artifact into a downstream pipeline:

# 1. Take a backup. The migrator does not snapshot for you.
cp -R bundles/run-2026-01-01-abc bundles/run-2026-01-01-abc.bak

# 2. Dry-run to see the planned change.
boruna migrate evidence-bundle bundles/run-2026-01-01-abc --dry-run

# 3. Apply, writing a sibling file you can diff.
boruna migrate evidence-bundle bundles/run-2026-01-01-abc

# 4. Review bundle.json.migrated; once happy, swap in place.
boruna migrate evidence-bundle bundles/run-2026-01-01-abc --in-place

For workflow.json the same pattern applies:

boruna migrate workflow-json examples/workflows/legacy/workflow.json --dry-run
boruna migrate workflow-json examples/workflows/legacy/workflow.json --in-place

What each migrator does

evidence-bundle

For a bundle directory:

• If bundle.json already exists, the migrator reports a no-op.
• Otherwise, it synthesizes a bundle.json summary containing format_version, boruna_version (default 0.6.0-pre when no embedded metadata pins it down), created_at (mtime of audit_log.json if present, otherwise current time), run_id (derived from the bundle directory name), workflow_hash (extracted from the first WorkflowStarted event in the audit log when readable; empty string when not), and components (sorted relative paths of every file in the bundle).
• The synthesized object includes synthesized: true so downstream tooling can distinguish a reconstructed summary from a runner-native one.
• When the bundle ALSO contains manifest.json (the canonical per-file checksum manifest from boruna-orchestrator), the migrator cross-checks it via verify_bundle and reports the result.

workflow-json

For a single workflow.json file:

• If schema_version: 1 is present, the migrator reports a no-op and the file is byte-identical afterwards.
• If schema_version is missing, the migrator adds it as 1.
• If schema_version is present and greater than 1, the migrator errors out — downgrading from a future schema is out of scope for the beta.
• If schema_version is some other value (negative, non-integer, string), the migrator rejects the input as malformed.

Note on field order: serde_json::Map in this workspace is a BTreeMap, so the migrated file’s keys land in lexicographic order. The semantic content is preserved; comments (which JSON does not support) are unaffected.

What the migrators do NOT do

• Reconstruct missing checksums. A legacy evidence bundle that never had manifest.json cannot grow one with hashes that match the original artifacts after the fact — that would manufacture a false integrity guarantee. The synthesized bundle.json is a summary, not a checksum manifest.
• Downgrade from a future schema. --to is forward-only in the beta.
• Touch persistence stores (runs.db). Database schema migrations are deferred to a follow-up sprint that will land alongside the next breaking persistence change.
• Edit examples/workflows/*/workflow.json retroactively. Those ship at the current schema with each release.

Coverage matrix (beta)

The matrix will expand in 1.x as additional breaking changes accumulate. Each future migrator will land with its own line in this table and a sprint reference in docs/roadmap.md.

Reporting issues

If boruna migrate rejects a bundle or workflow that you believe is valid 0.5.0 output, file an issue at https://github.com/escapeboy/boruna/issues with:

• The full migrator output (run with --dry-run first).
• A redacted copy of the bundle directory listing or workflow.json.
• The Boruna version that produced the artifact.

Edit this page on GitHub

Bundle Storage on S3

Sprint reference: post1-T-3.1.

The --bundle-storage s3://... flag tells boruna workflow run to copy the finalized evidence bundle to an S3 bucket after the local write succeeds. The local bundle remains the authoritative record; the S3 copy is an additional durable destination that survives the local data directory being wiped.

Status

• Adapter shipped: S3 (this guide). Works against AWS S3 and S3-compatible endpoints (MinIO, Cloudflare R2, Backblaze B2, LocalStack).
• Reserved schemes: gs:// (T-3.2, GCS) and azblob:// (T-3.3, Azure Blob) are rejected at parse time until those adapters ship.

Build with the s3 feature

The S3 adapter pulls in object_store + tokio + reqwest. To keep the default binary lean, the adapter is OFF by default. Enable it at build time:

# CLI binary (boruna)
cargo build --release --features boruna-cli/s3

# Direct orchestrator usage from another Rust crate
[dependencies]
boruna-orchestrator = { path = "...", features = ["s3"] }

When you build without the s3 feature and pass --bundle-storage s3://..., the URI rejects at parse time with a message that points you at the feature flag. Crucially: it never silently ignores the flag and ships an audit gap.

Configuring auth

object_store::aws::AmazonS3Builder::from_env() reads the standard AWS environment variables:

For production AWS, prefer instance/role credentials (the SDK picks those up automatically when none of the env vars above are set).

Required IAM permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket",
        "arn:aws:s3:::your-bucket/*"
      ]
    }
  ]
}

s3:DeleteObject is reserved for a future evidence prune flow; the current adapter does not delete objects.

Usage

Per-run

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=eu-west-1

boruna workflow run examples/workflows/llm_code_review \
  --policy allow-all \
  --record \
  --bundle-storage s3://my-audit-bucket/prod/llm-review

After the run finalizes locally, the CLI prints:

evidence bundle: ./data/evidence/<run-id>
  bundle_hash: <hex>
  audit_log_hash: <hex>
  files: 12
  storage_ref: s3://my-audit-bucket/prod/llm-review/<run-id>

Via env var

The flag falls back to BORUNA_BUNDLE_STORAGE, so operators typically set this once in their service environment:

export BORUNA_BUNDLE_STORAGE=s3://my-audit-bucket/prod

URI shape

The StorageRef returned by put is s3://bucket/prefix/<run-id>. Treat it as opaque; only the dispatcher parses it.

Reading bundles back

Once you have the storage_ref, use the orchestrator API to materialize the bundle into a local cache directory:

#![allow(unused)]
fn main() {
use boruna_orchestrator::audit::storage::{from_uri, StorageRef};

let storage = from_uri(Some("s3://my-audit-bucket/prod"))?.unwrap();
let local_dir = storage.get(&StorageRef("s3://my-audit-bucket/prod/<run-id>".into()))?;
// local_dir is now under BORUNA_BUNDLE_CACHE (defaults to <temp>/boruna-bundle-cache)
// and contains the same files the original run finalized locally.

boruna_orchestrator::audit::verify_bundle(&local_dir)?;
}

The cache directory is overwritten on each get. There is no automatic GC; sweep it periodically with find $BORUNA_BUNDLE_CACHE -mtime +N -delete or similar.

Failure semantics

A storage failure never masks a successful workflow. Conversely, operators who require S3 durability should monitor the warning output and re-run evidence verify against the local bundle to confirm it’s still on disk.

Error taxonomy

StorageError::Backend { kind, msg } uses these stable kinds for S3 operations:

StorageError::NotFound(ref) fires when get is called against a ref that has zero objects under its prefix.

Testing against MinIO locally

# Spin up MinIO
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  quay.io/minio/minio server /data --console-address ":9001"

# Create a bucket via the console (http://localhost:9001) or mc
mc alias set local http://localhost:9000 minioadmin minioadmin
mc mb local/boruna-audit

# Run boruna against it
export AWS_ENDPOINT_URL=http://localhost:9000
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_REGION=us-east-1
export AWS_ALLOW_HTTP=true

boruna workflow run examples/workflows/llm_code_review \
  --policy allow-all \
  --record \
  --bundle-storage s3://boruna-audit/local-test

The --features s3-it integration test under orchestrator/tests/ runs the full round-trip against a testcontainers-managed MinIO container; see orchestrator/tests/s3_integration.rs for the canonical example.

Determinism contract

storage_ref is operational metadata — it does not feed any audit-log hash or replay comparison. The bundle’s bundle_hash / audit_log_hash come from the local manifest and are independent of where the bundle is also stored.

Limitations

• No automatic bucket creation. The bucket must exist before you point boruna at it. Failure to find the bucket surfaces as s3.permanent.
• No multipart-upload tuning knob. object_store picks reasonable defaults (5 MB part size). Files smaller than that go via single PUT; larger ones use multipart automatically.
• The cache directory is shared across adapters — if you rotate between two buckets that contain different bundles for the same run_id, the cache content is whichever was fetched most recently. Operators who care about cross-bucket consistency should set BORUNA_BUNDLE_CACHE to a per-bucket directory.
• No retention / lifecycle policy is configured on the bucket; operators define this server-side via S3 lifecycle rules.

Edit this page on GitHub

Bundle Storage on Google Cloud Storage

Sprint reference: post1-T-3.2.

The --bundle-storage gs://... flag tells boruna workflow run to copy the finalized evidence bundle to a GCS bucket after the local write succeeds. The local bundle remains the authoritative record; the GCS copy is an additional durable destination.

This adapter mirrors the S3 adapter — same trait, same BORUNA_BUNDLE_CACHE semantics, same failure contract, just with GCS auth + the gs:// scheme.

Status

• Adapter shipped: GCS (this guide). Works against Google Cloud Storage and fsouza/fake-gcs-server for local testing.
• Already shipped: S3 (T-3.1). See bundle-storage-s3.md.
• Reserved scheme: azblob:// (T-3.3, Azure Blob) is rejected at parse time until that adapter ships.

Build with the gcs feature

# CLI binary (boruna)
cargo build --release --features boruna-cli/gcs

# Direct orchestrator usage from another Rust crate
[dependencies]
boruna-orchestrator = { path = "...", features = ["gcs"] }

# Combined with S3 if you operate multi-cloud
cargo build --release --features "boruna-cli/s3,boruna-cli/gcs"

When you build without the gcs feature and pass --bundle-storage gs://..., the URI rejects at parse time with a message that points you at the feature flag. Same UX guarantee as S3 — never silently ignored.

Configuring auth

object_store::gcp::GoogleCloudStorageBuilder::from_env() reads:

In production, prefer Workload Identity (GKE) or Service-Account-Attached-to-VM (GCE) — neither requires a key on disk.

Required IAM permissions

Bind a service account with the predefined role roles/storage.objectAdmin on the bucket, or the more granular:

storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.get
storage.objects.list

storage.objects.delete is reserved for a future evidence prune flow; the current adapter does not delete objects.

Usage

Per-run

export GOOGLE_APPLICATION_CREDENTIALS=/etc/boruna/sa.json
# Or for a key in env:
# export GOOGLE_SERVICE_ACCOUNT_KEY="$(cat /etc/boruna/sa.json)"

boruna workflow run examples/workflows/llm_code_review \
  --policy allow-all \
  --record \
  --bundle-storage gs://my-audit-bucket/prod/llm-review

After the run finalizes locally, the CLI prints:

evidence bundle: ./data/evidence/<run-id>
  bundle_hash: <hex>
  audit_log_hash: <hex>
  files: 12
  storage_ref: gs://my-audit-bucket/prod/llm-review/<run-id>

Via env var

export BORUNA_BUNDLE_STORAGE=gs://my-audit-bucket/prod

URI shape

The StorageRef returned by put is gs://bucket/prefix/<run-id>. Treat it as opaque; only the dispatcher parses it.

Reading bundles back

#![allow(unused)]
fn main() {
use boruna_orchestrator::audit::storage::{from_uri, StorageRef};

let storage = from_uri(Some("gs://my-audit-bucket/prod"))?.unwrap();
let local_dir = storage.get(&StorageRef("gs://my-audit-bucket/prod/<run-id>".into()))?;
boruna_orchestrator::audit::verify_bundle(&local_dir)?;
}

The cache directory (default <temp>/boruna-bundle-cache, overridable via BORUNA_BUNDLE_CACHE) is shared with the S3 adapter — set per-bucket cache dirs if you operate multi-cloud and care about cross-bucket consistency.

Failure semantics

Same as S3 (see bundle-storage-s3.md). A storage failure never masks a successful workflow.

Error taxonomy

StorageError::Backend { kind, msg } uses these stable kinds for GCS operations:

StorageError::NotFound(ref) fires when get is called against a ref that has zero objects under its prefix.

Testing against fake-gcs-server locally

# Spin up fake-gcs-server
docker run -p 4443:4443 \
  fsouza/fake-gcs-server:1.49.2 \
  -scheme http -host 0.0.0.0 -port 4443

# Create a bucket
curl -X POST 'http://localhost:4443/storage/v1/b?project=test-project' \
  -H 'Content-Type: application/json' \
  -d '{"name":"boruna-audit"}'

# Programmatic use from Rust:
use boruna_orchestrator::audit::storage_gcs::GcsBucketBuilder;
let store = GcsBucketBuilder::new("gs://boruna-audit/local-test")
    .with_endpoint("http://localhost:4443")
    .build()?;

(fake-gcs-server doesn’t need credentials; the adapter still calls from_env(), which simply doesn’t pick anything up — the endpoint override is what matters.)

The --features gcs-it integration tests under orchestrator/tests/ run the full round-trip against a testcontainers-managed fake-gcs-server container; see orchestrator/tests/gcs_integration.rs for the canonical example.

Determinism contract

storage_ref is operational metadata — it does not feed any audit-log hash or replay comparison. The bundle’s bundle_hash / audit_log_hash come from the local manifest and are independent of where the bundle is also stored.

Limitations

Same as S3: no automatic bucket creation, no multipart-upload tuning knob, shared cache directory across adapters, no retention/lifecycle policy (configure server-side via GCS Object Lifecycle rules).

Edit this page on GitHub

Bundle Storage on Azure Blob Storage

Sprint reference: post1-T-3.3.

The --bundle-storage azblob://... flag tells boruna workflow run to copy the finalized evidence bundle to an Azure Blob container after the local write succeeds. The local bundle remains the authoritative record; the Azure copy is an additional durable destination.

This adapter mirrors the S3 and GCS adapters — same trait, same BORUNA_BUNDLE_CACHE semantics, same failure contract, just with Azure auth + the azblob:// scheme.

Status

• Adapter shipped: Azure Blob Storage (this guide). Works against Azure proper and Azurite for local testing.
• With T-3.3 landing, all three remote schemes (S3, GCS, Azure) ship. The BundleStorage trait can graduate from #[doc(hidden)] to pub in a future doc PR.

Build with the azure feature

# CLI binary (boruna)
cargo build --release --features boruna-cli/azure

# Direct orchestrator usage from another Rust crate
[dependencies]
boruna-orchestrator = { path = "...", features = ["azure"] }

# All three remote schemes together
cargo build --release --features "boruna-cli/s3,boruna-cli/gcs,boruna-cli/azure"

When you build without the azure feature and pass --bundle-storage azblob://..., the URI rejects at parse time with a message that points you at the feature flag. Same UX guarantee as S3 / GCS — never silently ignored.

Configuring auth

object_store::azure::MicrosoftAzureBuilder::from_env() reads:

The account name comes from the URI (azblob://<account>/...), not the env, so a misconfigured AZURE_STORAGE_ACCOUNT_NAME won’t silently mismatch what the operator wrote.

In production, prefer Workload Identity (AKS) or Managed-Identity-Attached-to-VM — neither requires a key on disk.

Required RBAC roles

Bind a service principal or managed identity with the predefined role Storage Blob Data Contributor scoped to the container (or the storage account if you operate many containers per account).

URI shape

Unlike S3 (single-namespace) and GCS (single-namespace), Azure has a two-level namespace: storage account + blob container. Both are encoded in the URI so an operator can grep their config and see exactly which account a bundle landed in.

The StorageRef returned by put is azblob://account/container/prefix/<run-id>. Treat it as opaque; only the dispatcher parses it.

Usage

Per-run

export AZURE_STORAGE_ACCOUNT_KEY="$(cat /etc/boruna/azure-key)"

boruna workflow run examples/workflows/llm_code_review \
  --policy allow-all \
  --record \
  --bundle-storage azblob://myacct/audit-bundles/prod

Via env var

export BORUNA_BUNDLE_STORAGE=azblob://myacct/audit-bundles/prod

Reading bundles back

#![allow(unused)]
fn main() {
use boruna_orchestrator::audit::storage::{from_uri, StorageRef};

let storage = from_uri(Some("azblob://myacct/audit-bundles/prod"))?.unwrap();
let local_dir = storage.get(&StorageRef(
    "azblob://myacct/audit-bundles/prod/<run-id>".into()
))?;
boruna_orchestrator::audit::verify_bundle(&local_dir)?;
}

The cache directory (default <temp>/boruna-bundle-cache, overridable via BORUNA_BUNDLE_CACHE) is shared with the S3 and GCS adapters — set per-bucket cache dirs if you operate multi-cloud and care about cross-bucket consistency.

Failure semantics

Same as S3/GCS (see bundle-storage-s3.md). A storage failure never masks a successful workflow.

Error taxonomy

StorageError::Backend { kind, msg } uses these stable kinds for Azure operations:

StorageError::NotFound(ref) fires when get is called against a ref that has zero objects under its prefix.

Testing against Azurite locally

Programmatic use from Rust against an Azurite container:

#![allow(unused)]
fn main() {
use boruna_orchestrator::audit::storage_azure::AzureBlobBucketBuilder;

let store = AzureBlobBucketBuilder::new(
    "azblob://devstoreaccount1/boruna-audit/local-test"
)
.with_use_emulator(true)
.with_endpoint("http://localhost:10000/devstoreaccount1")
.build()?;
}

with_use_emulator(true) switches the SDK into Azurite mode (well-known account devstoreaccount1, well-known shared key). with_endpoint lets the SDK reach a non-default port.

Container creation against Azurite needs a SharedKey-signed PUT to ?restype=container — out of scope for the bundled adapter, which assumes the container exists. In a real test, create the container with the Azure CLI (az storage container create) or the Azure Storage Explorer.

Determinism contract

storage_ref is operational metadata — it does not feed any audit-log hash or replay comparison. The bundle’s bundle_hash / audit_log_hash come from the local manifest and are independent of where the bundle is also stored.

Limitations

• No automatic container creation. The container must exist before you point boruna at it. Failure to find it surfaces as azure.permanent. Create with az storage container create --name <container> --account-name <account>.
• No integration test in this build. Azurite requires SharedKey-signed container-create calls and object_store’s Azure adapter doesn’t expose a create_container primitive. Adding it would require either pulling in the full azure-storage crate or hand-rolling the SharedKey signing for a single test. The 18 unit tests cover URI parsing, path concatenation, ref-to-run-id extraction, and error classification — the Boruna-side logic. Verification against real Azure is the operator follow-up.
• No multipart-upload tuning knob. object_store picks reasonable defaults.
• Shared cache directory across adapters; set per-bucket if you care.
• No retention/lifecycle policy is configured; use Azure Storage’s built-in lifecycle management.

Edit this page on GitHub

KEK Rotation

Sprint reference: post1-T-2.4.

boruna evidence rotate-kek re-wraps the data-encryption-key (DEK) of one or more encrypted evidence bundles under a new key-encryption-key (KEK). The DEK itself is not changed — only the manifest’s wrapped_dek, wrapped_dek_nonce, and kek_id fields. Every per-file AES-GCM authentication tag in the bundle remains valid because the keying material that produced those tags hasn’t moved.

When to rotate

• A KEK is suspected leaked or has been retired in your KMS.
• A scheduled rotation policy (e.g. “rotate every 6 months”).
• Migrating bundles from a legacy kek_id to a new one.

Compliance auditors typically only need to see that rotation happened — the bundle’s bundle_hash updates because the manifest contents change, but the audit log inside the bundle is unchanged.

Single-bundle rotation

boruna evidence rotate-kek \
  /path/to/<run-id> \
  --old-kek $(printenv OLD_KEK_HEX) \
  --new-kek $(printenv NEW_KEK_HEX) \
  --kek-id-to "rotation-2026-q3"

The bundle’s manifest.json is rewritten atomically (sibling tmp + rename). The rest of the bundle directory is untouched.

Batch rotation

Point --target at a parent directory whose immediate subdirectories are bundles:

boruna evidence rotate-kek \
  /var/lib/boruna/evidence \
  --old-kek $OLD --new-kek $NEW \
  --kek-id-to "rotation-2026-q3" \
  --parallelism 4

Each bundle is processed in its own rayon task, bounded by --parallelism (default min(8, num_cpus)). Per-bundle failures do not abort the batch — already-rotated bundles stay rotated, and the failed bundle is reported on stderr. The CLI exits non-zero if any bundle failed.

Dry-run

Always dry-run first on a representative bundle:

boruna evidence rotate-kek bundles/abc... \
  --old-kek $OLD --new-kek $NEW --kek-id-to new-id \
  --dry-run

Dry-run validates that the old KEK can unwrap, that the new KEK re-wraps cleanly, and prints the planned kek_id change. No files are modified.

kek_id_from filter

Use --kek-id-from <id> to defend against accidental double-rotation in a mixed-state batch (some bundles already rotated, others not):

boruna evidence rotate-kek bundles/ \
  --old-kek $OLD --new-kek $NEW \
  --kek-id-from "rotation-2026-q2" \
  --kek-id-to "rotation-2026-q3"

Bundles whose current kek_id does not match --kek-id-from are reported as failures (bundle kek_id is 'X'; --kek-id-from is 'Y') without being modified.

Verifying after rotation

boruna evidence verify /path/to/<run-id> \
  --bundle-encryption-key $NEW_KEK_HEX

Verifying with the old KEK after rotation MUST fail with evidence.encryption_key_mismatch — that’s the regression the rotation tool’s tests assert on.

Spec reference

The 1.0 evidence-bundle reader contract already accommodates re-wrapping: per-file ciphertext stays valid because the DEK is unchanged. See docs/spec/evidence-bundle-1.0.md. No spec version bump is required for this feature.

Edit this page on GitHub

CLI Reference

The boruna binary is the primary interface for compiling, running, inspecting, and managing .ax programs and workflows.

Version

boruna --version (or -V) prints boruna <version>. The other binaries (boruna-mcp, boruna-pkg, boruna-orch) do the same.

Installation

cargo build --workspace
# Binary at: target/debug/boruna

To use boruna without cargo run --bin boruna --, add target/debug/ to your PATH or install with:

cargo install --path crates/llmvm-cli

Top-level commands

boruna <command> [options]

Commands:
  compile     Compile a .ax file to bytecode
  run         Run a .ax file
  trace       Run and emit an execution trace
  replay      Replay from a recorded event log
  inspect     Inspect a compiled module
  ast         Print the AST for a .ax file
  lang        Language diagnostics, repair, and the code registry
  doctor      Environment and toolchain health checks
  size        Bytecode artifact size report for a .ax file
  framework   Framework app validation and testing
  workflow    Workflow validation, execution, and graph inspection
  evidence    Evidence bundle inspection and verification
  template    Template listing and application
  skills      Embedded, agent-curated documentation
  trace2tests Generate regression tests from traces

boruna compile

Compile a .ax source file to bytecode.

boruna compile <file.ax>

Outputs the compiled module summary (functions, capabilities declared). Does not execute.

boruna run

Compile and run a .ax file.

boruna run <file.ax> [options]

Options:
  --policy <name>    Capability policy: allow-all, deny-all (default: deny-all)
  --record           Write an event log to .boruna/runs/<id>/
  --live             Enable real capability handlers (requires http feature)
  --trace            Emit a full execution trace to stdout
  --step-limit <n>   Abort if execution exceeds n steps
  --watch            Re-run on every change to the file (post-1.0)

Examples:

# Run in demo mode (no capabilities)
boruna run examples/hello.ax

# Run with all capabilities allowed
boruna run app.ax --policy allow-all

# Run with real HTTP (requires --features boruna-cli/http)
cargo run --features boruna-cli/http --bin boruna -- run app.ax --policy allow-all --live

# Watch mode — re-run on every save until Ctrl-C
boruna run app.ax --watch

Watch mode

--watch re-executes the file on every change. Filesystem events are debounced to 200ms, so a single editor save triggers exactly one rerun even on platforms that emit a flurry of events per save.

A separator line marks each rerun:

── reloading app.ax at 14:03:11 ──
3
steps: 4

A failed run (compile error or runtime panic) does not exit watch mode — the error is printed and the watcher waits for the next save. Press Ctrl-C to exit.

Watch combines with the standard run flags: boruna run app.ax --watch --policy ./policy.json --record events.json.

boruna trace

Run a .ax file and emit a step-by-step execution trace.

boruna trace <file.ax> [--policy <name>]

boruna replay

Replay execution from a recorded event log.

boruna replay <file.ax> --from <event-log-path> [--verify]

Options:
  --verify    Compare replay output to recorded output; fail if they differ

boruna inspect

Inspect a compiled bytecode module.

boruna inspect <file.ax>

Prints: function table, constant pool, declared capabilities, bytecode disassembly.

boruna ast

Print the parsed AST for a .ax file as JSON.

boruna ast <file.ax> [--json]

boruna lang

Language diagnostics and auto-repair.

boruna lang check <file.ax> [--json]
boruna lang repair <file.ax>
boruna lang codes [--json]

Subcommands:
  check     Run diagnostics: type errors, undeclared capabilities, unreachable code
  repair    Apply auto-repair suggestions from diagnostics
  codes     List the registry of stable diagnostic codes (E001–E010)

Examples:

# Check for errors with machine-readable output
boruna lang check app.ax --json

# Automatically repair issues
boruna lang repair app.ax

# Resolve a diagnostic code seen in `lang check --json` output
boruna lang codes --json

lang codes emits the registry from docs/reference/diagnostic-codes.md. Codes are stable forever — tools and agents may switch on them.

boruna doctor

Environment and toolchain health checks.

boruna doctor [--json]

Reports the binary version, which optional features were compiled in, whether a Rust toolchain is reachable, the persistent data directory’s writability, and whether the current directory looks like a Boruna project root. Read-only. Exits 1 if any check has error status.

boruna size

Bytecode artifact size report for a .ax source file.

boruna size <file.ax> [--json]

Compiles the file and reports per-function opcode counts, module-wide totals (functions, ops, constants, types, globals), and the serialized .axbc artifact byte size. Nothing is written to disk.

boruna confidence

Calibrated confidence for approval gates. See docs/design-conformal-gating.md.

boruna confidence threshold <calibration.json> --alpha-permille <1..999> [--score <0..1000>] [--json]

Reads a labelled calibration set and prints the score at or above which a gate may skip a human, so that a wrong answer is auto-approved with probability at most alpha. Also prints how the calibration set itself would have behaved at that threshold, and the decision for --score when given. When the set has too few wrong examples to certify alpha (at least ceil(1000 / alpha_permille) - 1 are needed), the threshold is never and every case goes to a human. Exits 1 on an invalid file or alpha.

boruna skills

Embedded, agent-curated documentation — compiled into the binary so an agent can learn Boruna from the installed binary alone.

boruna skills list [--json]
boruna skills get <name> [--json]
boruna skills emit <dir>
boruna skills pack "<query>" [--budget <tokens>] [--json]

Subcommands:
  list   List available skill documents
  get    Print one skill document (ax-language, cli, workflows, diagnostics)
  emit   Write every skill as <dir>/<name>/SKILL.md (name + description frontmatter)
  pack   Return only the sections relevant to a query, within a token budget

skills get exits 1 on an unknown skill name and lists the available names.

The cli skill ends with a command reference generated from the installed binary, so it lists exactly the commands and flags that exist. A unit test fails when a hand-written skill names a boruna <command> that does not exist.

skills emit is idempotent and overwrites existing files. skills pack ranks sections by keyword overlap with the query (ties broken by skill name and position), so the same query always returns the same bytes. --budget is an estimate (characters / 4, default 2000); the best section is truncated rather than dropped if it alone exceeds it. Exits 1 when nothing matches.

boruna framework

Validate and test framework apps (Elm-architecture .ax apps with init/update/view).

boruna framework validate <file.ax>
boruna framework test <file.ax> [options]

Options for test:
  -m <messages>    Comma-separated message sequence, e.g. "increment:1,reset:0"

Examples:

boruna framework validate examples/framework/counter_app.ax
boruna framework test examples/framework/counter_app.ax -m "increment:1,increment:1,reset:0"

boruna workflow

Validate and run workflow DAGs.

boruna workflow validate <workflow-dir/>
boruna workflow run <workflow-dir/> [options]

Options for run:
  --policy <name>    Capability policy (default: deny-all)
  --record           Write evidence bundle to .boruna/runs/<id>/
  --live             Enable real capability handlers
  --replay <dir>     Replay from an existing evidence bundle
  --verify           (with --replay) Verify outputs match recorded values

Examples:

# Validate DAG structure
boruna workflow validate examples/workflows/llm_code_review

# Run in demo mode
boruna workflow run examples/workflows/llm_code_review --policy allow-all

# Run and record evidence
boruna workflow run examples/workflows/llm_code_review --policy allow-all --record

# Run with real HTTP and LLM calls
cargo run --features boruna-cli/http --bin boruna -- \
  workflow run examples/workflows/llm_code_review \
  --policy allow-all --live --record

boruna workflow schedule

Run a workflow on a cron schedule. Loops until SIGINT (Ctrl-C).

boruna workflow schedule <workflow-dir/> [options]

Options:
  --cron <expr>            5-field cron expression (required), e.g. "*/5 * * * *"
  --policy <name>          Capability policy (default: deny-all)
  --data-dir <dir>         Directory for runs.db and per-run output (default: .boruna/data)
  --max-concurrency <n>    Maximum concurrent runs; skips tick if a run is already active (default: 1)
  --live                   Enable real capability handlers (requires http feature)

When a scheduled tick fires while a previous run is still active, that tick is skipped.

boruna workflow eval

Run a workflow against two LLM provider configurations and compare evidence bundles.

boruna workflow eval <workflow-dir/> --providers-a <file.json> --providers-b <file.json> [options]

Options:
  --providers-a <file>     First provider config JSON file (required)
  --providers-b <file>     Second provider config JSON file (required)
  --runs <n>               Runs per provider (default: 1)
  --data-dir <dir>         Directory for evidence bundles
  --json                   Machine-readable output

Reports per-step output agreement and timing differences between the two provider sets.

boruna workflow find

Recursively discover workflow.json files under a directory tree.

boruna workflow find [dir] [--json]

Validates each discovered workflow and prints path, name, step count, and validity. dir defaults to the current directory. Use --json for a JSON array.

boruna workflow graph

Emit the workflow DAG as structured graph facts.

boruna workflow graph <dir> [--json]

Reports nodes (each step’s kind, capabilities, and dependencies), edges, topological execution order, roots (steps with no dependencies), and leaves (steps nothing depends on). Read-only — only workflow.json is read, step source files are not. Exits 1 if the graph contains a cycle (is_dag: false).

boruna evidence

Inspect, verify, and manage evidence bundles.

boruna evidence create <run-id> --output-dir <dir> [--data-dir <dir>]
boruna evidence verify <bundle-dir/> [--bundle-encryption-key <hex>]
boruna evidence inspect <bundle-dir/> [--json] [--decrypt] [--bundle-encryption-key <hex>]
boruna evidence diff <bundle-a> <bundle-b> [--json]
boruna evidence gc-blobs [--data-dir <dir>] [--dry-run] [--json]
boruna evidence rotate-kek <target> --old-kek <hex> --new-kek <hex> [options]

Examples:

# Build a bundle from a completed run
boruna evidence create abc123def456 --output-dir ./bundles

# Inspect a bundle
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/ --json

# Verify a bundle
boruna evidence verify .boruna/runs/20260315-143022-abc4d/

evidence inspect

For plaintext (non-encrypted) bundles, evidence inspect automatically shows step output content from outputs/<step_id>/result.json. Each step output is truncated at 500 characters in text mode. With --json, the full parsed content appears under the "step_outputs" key. Encrypted bundles print a hint to stderr if --decrypt / --bundle-encryption-key is not supplied.

evidence create

Build an evidence bundle from a persisted run. Reads the run’s metadata, step checkpoints, and hash-chained audit log; writes a bundle directory with workflow.json, policy.json, per-step outputs, audit_log.json, env_fingerprint.json, and manifest.json. Bundles are created on demand — the runner does not auto-create them.

boruna evidence create <run-id> --output-dir <dir> [--data-dir <dir>]

The bundle is written to <output-dir>/<run-id>/.

evidence diff

Compare two evidence bundles side-by-side.

boruna evidence diff <bundle-a> <bundle-b> [--json]

Reports differences in workflow metadata, step outputs, audit event counts, and verification status. Use --json for machine-readable output.

Examples:

boruna evidence diff .boruna/runs/run-baseline/ .boruna/runs/run-rerun/
boruna evidence diff baseline/ rerun/ --json

evidence gc-blobs

Sweep orphaned content-addressed blobs from the data directory.

boruna evidence gc-blobs [--data-dir <dir>] [--dry-run] [--json]

An orphan is a blob file no longer referenced by any run checkpoint. Reports {deleted, skipped, bytes_freed}. Use --dry-run to report without deleting.

evidence rotate-kek

Rotate the key-encryption key (KEK) on one or more encrypted bundles without re-encrypting file content.

boruna evidence rotate-kek <target> --old-kek <hex> --new-kek <hex> [options]

Options:
  --kek-id-from <id>     Only rotate bundles whose current kek_id matches (safety check)
  --kek-id-to <id>       kek_id written to the rotated manifest (default: "default")
  --dry-run              Print planned actions without modifying any bundle
  --parallelism <n>      Parallel bundle limit in batch mode (default: min(8, num_cpus))

<target> may be a single bundle directory or a parent directory whose immediate subdirectories are bundles (batch mode).

boruna template

List and apply app templates.

boruna template list
boruna template apply <name> [options]

Options for apply:
  --args <key=value,...>    Template variable substitutions
  --validate                Validate the generated output after applying

Examples:

boruna template list
boruna template apply crud-admin --args "entity_name=products,fields=name|price" --validate

Available templates: crud-admin, form-basic, auth-app, realtime-feed, offline-sync

boruna trace2tests

Generate regression tests from execution traces.

boruna trace2tests <trace-file> --output <test-dir/>

See TRACE_TO_TESTS.md for details.

Global options

  --help      Print help for any command
  --version   Print the Boruna version

Edit this page on GitHub

Command reference

Generated from boruna 3.5.0 --help when this site was built. For explanations and examples see the CLI guide.

boruna compile

• boruna compile <FILE> [--output] — Compile a .ax source file to bytecode

boruna run

• boruna run <FILE> [--policy] [--max-steps] [--record] [--live] [--record-net-to] [--replay-net-from] [--watch] [--providers] — Run a .ax source file or bytecode file

boruna trace

• boruna trace <FILE> — Run with execution tracing enabled

boruna replay

• boruna replay <FILE> <LOG> — Replay execution from a recorded event log

boruna inspect

• boruna inspect <FILE> — Inspect a bytecode file

boruna ast

• boruna ast <FILE> — Dump the AST of a .ax source file

boruna fmt

• boruna fmt <FILE> [--check] — Format a .ax source file (canonical pretty-print)

boruna framework

• boruna framework — Framework commands
• boruna framework new <NAME> [--dir] — Create a new framework app from template
• boruna framework validate <FILE> — Validate a .ax file conforms to the App protocol
• boruna framework test <FILE> [--messages] — Run a framework app interactively with messages
• boruna framework inspect-state <FILE> [--messages] — Inspect framework app state after running messages
• boruna framework simulate <FILE> <MESSAGES> — Simulate a sequence of messages and display state transitions
• boruna framework inspect <FILE> [--json] — Print App contract summary (State, Messages, Effects) — machine-readable
• boruna framework diag <FILE> [--messages] — Structured diagnostics output (JSON)
• boruna framework trace-hash <FILE> [--messages] — Run with tracing and print a stable hash of the trace
• boruna framework replay <FILE> <LOG> — Replay a recorded cycle log and verify determinism

boruna lang

• boruna lang — Language tooling commands (diagnostics, repair)
• boruna lang check <FILE> [--json] [--output] — Check a source file and report diagnostics
• boruna lang repair <FILE> [--from] [--apply] — Repair a source file using diagnostic suggestions
• boruna lang codes [--json] — List the registry of stable diagnostic codes
• boruna lang caps <FILE> [--json] — Report each function’s declared vs. inferred-needed capabilities and flag over-declarations (capabilities granted but never used)

boruna doctor

• boruna doctor [--json] — Environment and toolchain health checks

boruna size

• boruna size <FILE> [--json] — Report the bytecode artifact size of a .ax source file

boruna skills

• boruna skills — Embedded, agent-curated documentation (list, get, emit, pack)
• boruna skills list [--json] — List available agent skill documents
• boruna skills get <NAME> [--json] — Print an agent skill document by name
• boruna skills emit <DIR> — Write every skill as <DIR>/<name>/SKILL.md for an agent to load
• boruna skills pack <QUERY> [--budget] [--json] — Return only the skill sections relevant to a query, within a token budget

boruna confidence

• boruna confidence — Calibrated confidence for approval gates (threshold)
• boruna confidence threshold <FILE> [--alpha-permille] [--score] [--json] — Show the auto-approve threshold a calibration file gives for a target false approval rate, and optionally the decision for one score

boruna trace2tests

• boruna trace2tests — Trace-to-test tools (record, generate, run, minimize)
• boruna trace2tests record <FILE> [--messages] [--out] — Record an execution trace from a framework app
• boruna trace2tests generate [--trace] [--name] [--out] — Generate a test spec from a recorded trace
• boruna trace2tests run [--spec] [--source] — Run a test spec against source code
• boruna trace2tests minimize [--trace] [--source] [--predicate] [--out] — Minimize a failing trace using delta debugging

boruna template

• boruna template — Template tools (list, apply, validate)
• boruna template list [--dir] — List available templates
• boruna template apply <NAME> [--dir] [--args] [--out] [--validate] — Apply a template with arguments

boruna literate

• boruna literate — Literate workflow specs — extract embedded .ax/.qnt code fences from a markdown narrative into per-file outputs. See docs/architecture-literate-workflows.md
• boruna literate extract <FILE> [--out-dir] [--json] [--verbose] — Extract <lang> <filename> += code fences from a markdown document into per-file outputs. Accepted languages: ax, boruna, quint. Other fences (rust, bash, …) are ignored. See docs/architecture-literate-workflows.md

boruna repl

• boruna repl <FILE> [--policy] — Interactive REPL for .ax modules — load a file, evaluate expressions interactively, inspect the environment. See docs/architecture-boruna-repl.md

boruna simulate

• boruna simulate <DIR> [--max-samples] [--seed] [--policy] [--invariant] [--witnesses] [--json] — Random property-based simulation of a workflow. Runs the workflow N times under a user-supplied invariant (and optional witnesses) and reports violation count + witness frequencies. See docs/architecture-boruna-simulate.md

boruna new

• boruna new <TEMPLATE> [--dir] [--target] [--var] [--no-input] [--force] — Scaffold a new project from a template (interactive)

boruna workflow

• boruna workflow — Workflow execution and validation
• boruna workflow validate <DIR> [--print-hash] — Validate a workflow definition directory
• boruna workflow run <DIR> [--policy] [--record] [--evidence-dir] [--encrypt-bundle] [--bundle-encryption-key] [--bundle-kek-id] [--live] [--data-dir] [--ephemeral] [--concurrency] [--skip-if-running] [--submit-only] [--expect-workflow-hash] [--bundle-storage] [--providers] — Run a workflow
• boruna workflow approve <RUN_ID> <STEP_ID> [--data-dir] — Approve a paused approval-gate step. Records an approval sentinel in the run’s metadata; the operator must run boruna workflow resume <run-id> afterward to advance the run past the gate
• boruna workflow reject <RUN_ID> <STEP_ID> [--reason] [--data-dir] — Reject a paused approval-gate step. Records a rejection sentinel; boruna workflow resume <run-id> will then halt the run as Failed with the optional reason as the error message
• boruna workflow trigger <RUN_ID> <STEP_ID> [--token] [--payload] [--payload-file] [--data-dir] — Trigger a paused external_trigger step (sprint 0.3-S15). Records the supplied payload as the step’s output and primes resume to advance past the gate. Operator must run boruna workflow resume <run-id> afterward to actually execute downstream steps
• boruna workflow show <RUN_ID> [--json] [--data-dir] — Show the full state of a single run: row, step checkpoints, and approval-gate decisions. Use --json for machine-readable output (jq-friendly). Reads from the same --data-dir as run/resume
• boruna workflow list [--status] [--json] [--data-dir] — List runs in the persistent store. Optional –status filter
• boruna workflow resume <RUN_ID> [--data-dir] [--workflow-dir] [--policy] [--live] [--concurrency] [--expect-workflow-hash] — Resume a previously-paused or crashed workflow run by id
• boruna workflow schedule <DIR> [--cron] [--policy] [--data-dir] [--max-concurrency] [--live] — Run a workflow on a cron schedule in a long-running daemon process. Validates the cron expression on startup (fail fast), then loops: sleep until next fire time → invoke the runner API → log outcome. Ctrl-C / SIGTERM finish any in-progress run then exit cleanly
• boruna workflow eval <WORKFLOW_DIR> [--providers-a] [--providers-b] [--runs] [--data-dir] [--json] — Run the same workflow against two LLM provider configs and compare outputs
• boruna workflow find <DIR> [--json] — Find and inspect workflow definitions under a directory tree
• boruna workflow graph <DIR> [--json] — Emit the workflow DAG as structured graph facts

boruna evidence

• boruna evidence — Evidence bundle inspection and verification
• boruna evidence create <RUN_ID> [--output-dir] [--data-dir] — Build an evidence bundle from a persisted run (sprint 0.4-S10). Reads the run’s metadata, step checkpoints, and hash-chained audit log; writes a bundle directory containing workflow.json, policy.json, per-step outputs, audit_log.json, env_fingerprint.json, and a manifest.json with bundle hash + per-file checksums
• boruna evidence verify <DIR> [--bundle-encryption-key] [--expected-bundle-hash] [--require-encryption] [--verify-key] [--require-signature] — Verify an evidence bundle for integrity
• boruna evidence inspect <DIR> [--json] [--itf] [--decrypt] [--bundle-encryption-key] — Inspect an evidence bundle’s manifest
• boruna evidence gc-blobs [--data-dir] [--dry-run] [--json] — Sweep orphan blobs from the data-dir’s blobs/ tree (sprint W3-B). An orphan is a content-addressed blob file no longer referenced by any step_checkpoints.output_blob_ref row. Reports {deleted, skipped, bytes_freed}. Holds an exclusive write lock on runs.db for the duration of the sweep — see docs/design-blob-gc.md for the TOCTOU rationale
• boruna evidence rotate-kek <TARGET> [--old-kek] [--new-kek] [--kek-id-from] [--kek-id-to] [--dry-run] [--parallelism] — Rotate the KEK on one or more encrypted evidence bundles (post1-T-2.4). Unwraps the DEK with the old KEK, re-wraps it under the new KEK, and atomically rewrites each bundle’s manifest.json. Per-file ciphertext is unchanged because the DEK itself does not change
• boruna evidence redact <DIR> [--event] [--field] [--reason] — Verifiably redact one audit-log entry in an evidence bundle so PII can be removed from a SEALED bundle without breaking verification
• boruna evidence diff <BUNDLE_A> <BUNDLE_B> [--json] — Compare two evidence bundles side-by-side (post1-evidence-diff). Reports differences in workflow metadata, step outputs, audit event counts, and verification status
• boruna evidence attest <DIR> [--verify] [--signing-key] [--verify-key] [--output] — Emit (or verify) an in-toto Statement + DSSE envelope for the bundle’s runtime provenance, for interop with the supply-chain ecosystem (cosign verify-blob, in-toto-verify). Additive — does NOT touch the native bundle format. Writes attestation.intoto.dsse.json into the bundle directory
• boruna evidence anchor <DIR> [--rekor-url] [--offline] [--verify] [--output] — Anchor a signed bundle in a Sigstore Rekor transparency log, adding an external witness + trusted timestamp on top of the bundle’s own hash chain (closes the “trust the recorder / silent backdating” hole). Builds a hashedrekord entry from the manifest’s bundle_hash + ed25519 signature. Three modes:
• boruna evidence report <DIR> [--framework] [--format] — Generate a human-readable COMPLIANCE evidence-mapping report that maps a bundle’s actual contents to the specific regulatory obligation each one helps satisfy. Verifies the bundle first and stamps the verdict at the top; a tampered/unverifiable bundle produces a report that says so loudly. This is a technical mapping, NOT a certificate of compliance
• boruna evidence otel <DIR> [--out] — Export the bundle’s execution as OpenTelemetry spans in OTLP/JSON — the file format any OTel collector ingests. No SDK dependency, no network: emit the document and POST it to a collector (or pipe it through the otlpjson file receiver) to surface the run in Jaeger, Tempo, Honeycomb, Datadog, etc

boruna capability

• boruna capability — Capability surface inspection (versioned identity for caching)
• boruna capability list [--json] — List all capabilities this binary exposes, with stable identity hash. Use capability_set_hash as part of a cache key to safely memoize deterministic results across binary upgrades. See docs/reference/capability-identity.md

boruna metrics

• boruna metrics — Prometheus metrics export from the persistent run store (sprint 0.4-S12). See docs/design-prometheus-metrics.md for the architectural decision and operator integration pattern (cron + node_exporter’s textfile collector)
• boruna metrics export [--data-dir] — Export current metrics in Prometheus text format to stdout. Pipe to a .prom file under node_exporter’s textfile collector directory:

boruna policy

• boruna policy — Policy file validation and inspection (sprint 0.4-S15). See docs/design-policy-as-code.md and docs/reference/policy-schema.md for the schema and the stable error_kind taxonomy
• boruna policy validate <FILE> [--json] — Strict-validate a policy file. Exits 0 on ok, 2 on validation error, 1 on file IO error. Designed as a CI gate
• boruna policy show <FILE> — Validate then print the effective policy in human-readable form: default behavior, denormalized rule list, net policy bounds

boruna migrate

• boruna migrate <KIND> <PATH> [--from] [--to] [--dry-run] [--in-place] — Migration tooling beta (sprint W5-C). Upgrades pre-1.0 Boruna artifacts to the current on-disk format. See docs/guides/migration.md for the coverage matrix and recommended workflow

.ax Language Reference

Looking for the formal specification? This page is the narrative, example-driven reference. The authoritative grammar, type rules, and capability semantics live in docs/spec/ax-language-1.0.md. When the two disagree, the spec wins.

.ax is Boruna’s statically-typed, deterministic scripting language. It compiles to Boruna bytecode and runs on the Boruna VM. It is designed for workflow steps: small, focused, pure functions with explicit capability declarations for any side effects.

File structure

Every standalone .ax file must define fn main() -> Int. The main function is the entry point for boruna run.

fn main() -> Int {
    42
}

Types

Variables

Use let with an explicit type annotation:

let name: String = "Boruna"
let count: Int = 0
let flag: Bool = true

A binding that you want to change later is declared with let mut and rebound with =:

let mut total: Int = 0
total = total + 5

Rebinding changes what the name refers to; values themselves (records, lists, maps) are never modified in place. Reassigning a binding declared without mut still compiles, but boruna lang check reports warning E010 and boruna lang repair adds the missing mut. It will be a compile error in language version 2.0.

Loops

fn sum(items: List<Int>) -> Int {
    let mut total: Int = 0
    for x in items {
        total = total + x
    }
    total
}

fn factorial(n: Int) -> Int {
    let mut result: Int = 1
    let mut i: Int = n
    while i > 0 {
        result = result * i
        i = i - 1
    }
    result
}

for iterates a List in order; the loop variable and any let inside the body are scoped to the body. A loop that never ends is stopped by the step limit (--step-limit) with a runtime error. Recursion still works and is often the clearer choice.

No semicolons. Each statement is on its own line.

Functions

fn add(a: Int, b: Int) -> Int {
    a + b
}

The last expression in a function body is the return value. No return keyword needed.

Capability annotations

Functions that perform side effects must declare the required capabilities:

fn fetch(url: String) -> String !{net.fetch} {
    // live implementation
}

fn call_model(prompt: String) -> String !{llm.call} {
    // live implementation
}

// Multiple capabilities
fn fetch_and_cache(url: String) -> String !{net.fetch, fs.write} {
    // live implementation
}

Without the annotation, the VM will reject any attempt to call the capability at runtime.

Intent declarations

A function may declare a single machine-read purpose with an intent "..." clause after its signature. The clause is optional and order-independent with capability and contract clauses:

fn transfer(amount: Int) -> Int !{db.write} intent "Move funds between accounts" {
    // implementation
}

Intent is captured into the run’s evidence bundle (intents.json, keyed by step id) so an auditor sees what each step was authorized to do alongside what it actually did. It is covered by the bundle checksums, so tampering with a captured intent makes boruna evidence verify fail. A function may declare at most one intent; a second is a compile error.

Contracts (requires)

A function may declare one or more requires <expr> preconditions, checked at runtime against its arguments on entry:

fn transfer(amount: Int) -> Int !{db.write} requires amount > 0 {
    // runs only if amount > 0
}

If a precondition is false when the function is called, execution traps with a contract violation carrying a counterexample — the concrete arguments that triggered it (e.g. [0]) — so the failing input is reproducible. In a workflow, the violation surfaces with the stable error_kind contract_violation and the counterexample is recorded in the run’s hash-chained audit log (tamper-evident evidence). A violation is deterministic in the inputs, so it is not retry-eligible.

Contracts are enforced purely at runtime (concrete-trace checking) — Boruna does not use SMT/symbolic proving. ensures postconditions are parsed but not yet enforced.

Records

Define named record types with the type keyword:

type Point {
    x: Int,
    y: Int,
}

let p: Point = Point { x: 3, y: 4 }
let px: Int = p.x

Record spread creates an updated copy:

let p2: Point = Point { ..p, y: 10 }

Enums

Each variant is either a unit variant or carries a single payload value. Construct a value with the EnumName::Variant(payload) form (unit variants take no parentheses):

enum Shape {
    Circle(Float),
    Square(Float),
}

let s: Shape = Shape::Circle(5.0)

Pattern matching

let result: String = match s {
    Circle(radius) => "circle"
    Square(side) => "square"
    _ => "unknown"
}

Match on Option:

let value: Option<Int> = Some(42)
let n: Int = match value {
    Some(x) => x
    None => 0
}

Match on Result:

let r: Result<Int, String> = Ok(99)
let out: Int = match r {
    Ok(v) => v
    Err(_) => -1
}

Match on strings:

let greeting: String = match lang {
    "en" => "hello"
    "es" => "hola"
    _ => "hi"
}

Conditionals

let label: String = if score > 90 {
    "pass"
} else {
    "fail"
}

Lists

let items: List<Int> = [1, 2, 3, 4, 5]

List operations are available through the standard library.

Maps

let config: Map<String, Int> = { "timeout": 30, "retries": 3 }

Framework apps

Framework apps implement the Elm architecture. They must define:

fn init() -> State { ... }
fn update(state: State, msg: Msg) -> UpdateResult { ... }
fn view(state: State) -> UINode { ... }

Where State, Msg, Effect, UpdateResult, UINode, and PolicySet are the framework protocol types. See FRAMEWORK_SPEC.md for the full protocol.

Syntax quick reference

// Comments use double-slash

// Variables (type required; add `mut` to rebind later)
let x: Int = 42
let mut n: Int = 0
n = n + 1

// Loops
for item in [1, 2, 3] { n = n + item }
while n > 0 { n = n - 1 }

// Function
fn square(n: Int) -> Int {
    n * n
}

// Capability function
fn now() -> Int !{time.now} {
    // implementation
}

// Record literal
Point { x: 1, y: 2 }

// Record spread
Point { ..point, x: 10 }

// Enum variant
Shape::Circle(5.0)

// Pattern match
match x {
    0 => "zero"
    _ => "nonzero"
}

// Option
Some(42)
None

// Result
Ok("value")
Err("message")

// List
[1, 2, 3]

// Map
{ "key": "value" }

Import statements

import "std-name"

Import statements load a standard library package at compile time. The library source is inlined into the compilation unit before type-checking. The import line itself is removed from the compiled output.

Standard library packages are resolved from the libs/ directory relative to the current working directory. When a library source is inlined, any fn main() -> Int stub present in the library file is stripped so it does not conflict with the importing program’s own main.

Example:

import "std-json"

fn main() -> Int {
    let s: String = int_to_string(42)
    0
}

Built-in functions

These functions are provided by the runtime and do not need to be imported:

These built-ins are also wrapped in std-json (via int_to_string, json_escape) and can be called directly in any .ax file.

Note on naming: The __builtin_ prefix distinguishes these from user-defined functions and prevents shadowing. User-facing wrappers in stdlib packages use cleaner names.

What .ax is not

.ax is deliberately minimal. It does not have:

• Mutable variables (use record spread for state transitions)
• Loops (use recursion or standard library functions)
• Exceptions (use Result<T, E>)
• Implicit side effects (every effect must be declared)
• Generics (types are concrete at definition time)

These omissions are intentional. They keep the language deterministic and auditable.

Edit this page on GitHub

MCP Server Tool Reference

The boruna-mcp binary exposes Boruna’s toolchain to AI coding agents (Claude Code, Cursor, Codex, …) over a JSON-RPC stdio transport. This page documents the wire contract for every tool — parameter names, types, return shapes, and error_kind values.

If you only want to register the server in your IDE, see AGENTS.md. The Rust source of record is crates/boruna-mcp/src/server.rs.

Quick start

# Register the server in your IDE's MCP config (e.g. .mcp.json for Claude Code):
{
  "mcpServers": {
    "boruna": {
      "command": "boruna-mcp",
      "args": ["--templates-dir", "/path/to/templates", "--libs-dir", "/path/to/libs"],
      "env": {}
    }
  }
}

Both --templates-dir and --libs-dir are optional. Defaults are templates and libs relative to the working directory.

Conventions

The tools below share several conventions:

• All tools return JSON inside an MCP Content::text payload. Responses are pretty-printed.
• Every response — success and failure — carries protocol_version: 1. This is the wire-format version of the response envelope. It bumps only on a breaking shape change (field rename, removal, type change, or error_kind semantics change). Additive changes keep the version. Integrators should reject any response whose protocol_version exceeds the version they were built against, and may safely upgrade their parsers when the field stays the same. See the Stability section for the full versioning policy.
• Domain errors are returned as success: false JSON, not as MCP errors. This includes compile failures, runtime errors, validation errors, parse errors, etc. MCP-protocol errors (returned as McpError) are reserved for transport-level problems — most commonly when a source argument exceeds the 1 MB limit enforced by every source-accepting tool.
• Source code is passed as a string, not a file path. Tool callers are responsible for reading files themselves.
• Synchronous Boruna APIs run inside tokio::task::spawn_blocking. That means tool calls don’t starve the MCP event loop, but each call is single-threaded.
• success: true responses always include the success flag. Field shapes after the flag vary per tool — see each section.
• error_kind values are stable strings. Integrators may switch on them safely. New error_kind values may be added in a non-breaking way; existing ones are not renamed.

Tools

Note on the JSON examples below: for brevity, the per-tool examples show only the body fields. Every actual response — success and failure — also includes "protocol_version": 1 immediately after "success". See the Conventions and Stability sections for the full contract.

boruna_compile

Compile .ax source code and return module info.

Parameters

Returns (success)

{
  "success": true,
  "module": {
    "name": "module",
    "version": 1,
    "functions": 3,
    "types": 1,
    "constants": 7,
    "entry": 0
  }
}

Returns (failure)

{
  "success": false,
  "errors": [
    { "severity": "error", "code": "E001", "message": "...", "line": 10, "col": 5 }
  ]
}

Error codes: E001 (lexer), E002 (parser), E008 (codegen), E009 (typechecker).

boruna_ast

Parse .ax source code and return the AST as JSON.

Parameters

Returns (success)

{
  "success": true,
  "truncated": false,
  "ast": { /* program AST as JSON */ }
}

If the AST exceeds 100 KB, the tool returns the truncated string and metadata instead of the parsed object:

{
  "success": true,
  "truncated": true,
  "ast_size": 134217,
  "ast": "..."
}

Returns (failure) — same errors shape as boruna_compile (lexer or parser errors only), or the following if AST JSON serialization itself fails (rare):

{ "success": false, "error_kind": "serialization_error", "message": "..." }

boruna_run

Compile and execute .ax source code under a capability policy.

Parameters

There is no input parameter. Script authors interpolate runtime values as literals into the .ax source before submission. This keeps the determinism contract clean: the (source, policy) tuple fully determines the run.

Returns (success)

{
  "success": true,
  "result": <value>,
  "steps": 142,
  "ui_output": [<value>, ...]
}

If trace: true:

{
  "success": true,
  "result": <value>,
  "steps": 142,
  "ui_output": [],
  "trace": ["op:0", "op:1", ...],
  "trace_truncated": false
}

The trace is capped at 500 entries; trace_truncated: true indicates the suffix was discarded.

Returns (failure)

{ "success": false, "error_kind": "runtime_error",  "message": "...", "steps": 7 }
{ "success": false, "error_kind": "invalid_policy", "message": "..." }

Plus the errors shape from boruna_compile if compilation fails before the run starts.

error_kind values: runtime_error, invalid_policy. Compile failures are returned without an error_kind (they use the errors array). Exceeding max_steps is reported as runtime_error with a step-limit message — there is no distinct kind for it.

Value encoding — primitives are passed through directly (Int → number, String → string, Bool → bool, Unit → null). Tagged values use the shapes:

{"option": "None"}                         // Value::None
{"option": "Some", "value": <inner>}       // Value::Some
{"result": "Ok",   "value": <inner>}       // Value::Ok
{"result": "Err",  "value": <inner>}       // Value::Err
{"type": "record", "type_id": 4, "fields": [...]}
{"type": "enum",   "type_id": 6, "variant": "Tag", "payload": <inner>}
{"actor_id": 1}                            // Value::ActorId
{"fn_ref": 12}                             // Value::FnRef

Value::List becomes a JSON array; Value::Map becomes a JSON object.

Progress notifications (formalized as 1.x stable in post1-T-1.1; underlying mechanism shipped in sprint 0.4-S6).

When the caller includes a progressToken in the request’s _meta field — the standard MCP mechanism for streaming progress — the server drives the VM through Vm::execute_bounded in slices of ~100,000 opcodes. Between slices it emits MCP notifications/progress events whose progress field is the cumulative VM step count:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "<echoed from request>",
    "progress": 142000
  }
}

The events are coarse — slice-bounded, not per-opcode — so a long-running script emits several events per second on typical hardware. Clients that don’t supply a progressToken see no notifications and no extra latency. The streaming and non-streaming paths share their semantics for start_time, max_wall_ms, error handling, and final response shape, so progress-aware clients see identical results to legacy clients on the same input.

boruna_check

Run diagnostics on .ax source.

Parameters

Returns

{
  "success": true,
  "file": "<source>",
  "diagnostics_count": 2,
  "diagnostics": [
    {
      "id": "MISSING_MAIN",
      "severity": "error",
      "message": "...",
      "location": { "file": "<source>", "line": 1, "col": 1, "end_line": 1, "end_col": 1 },
      "patches": [
        {
          "id": "add_main",
          "description": "...",
          "confidence": "High",
          "rationale": "..."
        }
      ]
    }
  ]
}

location and patches are present only when applicable. confidence is one of "High", "Medium", "Low".

This tool returns success: true even when diagnostics are found — diagnostics are findings, not failures. Check diagnostics_count and per-entry severity to react.

boruna_repair

Auto-repair .ax source using diagnostic patches.

Parameters

Returns

{
  "success": true,
  "repaired_source": "<the modified .ax source>",
  "patches_applied": 2,
  "patches_skipped": 0,
  "applied": [{ "diagnostic_id": "...", "patch_id": "...", "description": "..." }],
  "skipped": [{ "diagnostic_id": "...", "reason": "..." }],
  "verify_passed": true,
  "diagnostics_before": 2,
  "diagnostics_after": 0
}

verify_passed: true means re-running diagnostics on the repaired source produced no errors. Always inspect diagnostics_after before trusting the repair.

boruna_validate_app

Validate that .ax source conforms to the App protocol (Elm-style init / update / view).

Parameters

Returns

{
  "success": true,
  "has_init": true,
  "has_update": true,
  "has_view": true,
  "has_policies": false,
  "state_type": "State",
  "message_type": "Msg",
  "errors": [],
  "valid": true
}

valid: true when errors is empty AND all three of has_init / has_update / has_view are true.

Returns (failure) — success: false, error_kind: "framework_error" if the validator itself crashed; compile errors use the errors shape from boruna_compile.

boruna_framework_test

Run a framework App by sending a sequence of messages.

Parameters

Returns

{
  "success": true,
  "init_state": <value>,
  "cycles": [
    { "message": "increment:1", "state": <value>, "effects": 0, "ui_tree": <value or null> },
    ...
  ],
  "final_state": <value>,
  "total_cycles": 2
}

If a cycle fails, the tool returns success: false, error_kind: "framework_error", and includes the partial cycles (with the failing entry containing an error field) plus the init_state so callers can debug the divergence.

Value formatting in this tool is brief (different from boruna_run — see source format_value_brief): records render as flat field arrays, enums as {variant, payload}, options/results as {Tag: value}.

boruna_workflow_validate

Validate a workflow definition (JSON).

Parameters

Returns

{
  "success": true,
  "workflow_name": "code_review",
  "workflow_version": "1.0.0",
  "steps_count": 3,
  "edges_count": 2,
  "execution_order": ["fetch_pr", "analyze", "post_comment"]
}

Returns (failure)

{ "success": false, "error_kind": "parse_error",      "message": "..." }
{ "success": false, "error_kind": "validation_error", "errors": [{ "kind": "Cycle", "message": "..." }] }

error_kind: "parse_error" means the JSON itself was malformed. validation_error means the JSON parsed but the DAG is invalid (cycle, missing step reference, etc.). Each entry in errors carries a kind (debug-formatted Rust enum variant) and a human-readable message.

boruna_template_list

List available Boruna app templates.

Parameters — none.

Returns

{
  "success": true,
  "count": 5,
  "templates": [
    {
      "name": "crud-admin",
      "version": "1.0.0",
      "description": "...",
      "dependencies": ["std-ui", "std-forms"],
      "capabilities": ["db.query"],
      "args": ["entity_name", "fields"]
    }
  ]
}

args lists only the variable names; consult template apply for substitution.

Returns (failure) — success: false, error_kind: "template_error", message: ... (e.g. when the templates dir doesn’t exist or contains malformed manifests).

boruna_template_apply

Apply a template with variable substitution.

Parameters

Returns

{
  "success": true,
  "template_name": "crud-admin",
  "output_file": "...",
  "source": "<rendered .ax source>",
  "dependencies": ["std-ui"],
  "capabilities": ["db.query"],
  "validation": { "passed": true }
}

The validation object is present only when validate: true. If validation fails:

"validation": { "passed": false, "error": "..." }

Returns (failure)

{ "success": false, "error_kind": "invalid_args",   "message": "argument must be key=value format, got: ..." }
{ "success": false, "error_kind": "template_error", "message": "..." }

Limits

• Source size: every tool that accepts a source parameter rejects payloads above 1 MB at the MCP layer (returned as an MCP invalid_params error, not as JSON). This is enforced in crates/boruna-mcp/src/server.rs::validate_source.
• AST size (boruna_ast): ASTs above 100 KB are returned truncated as a string (with truncated: true and ast_size), not as a parsed JSON object.
• Trace size (boruna_run): execution traces are capped at 500 entries (trace_truncated indicates suffix discarded).
• Process model: all tool calls run synchronously inside spawn_blocking. The MCP server is single-tenant by design; long-running tool calls block the response, not the event loop.

Stability

• protocol_version: 1 is the wire-format version of the response envelope, present on every tool response (success and failure). Locked by crates/boruna-mcp/src/tools/mod.rs::TOOL_RESPONSE_PROTOCOL_VERSION; a regression test (protocol_version_tests) asserts coverage across both success and failure paths of every tool. Bumped only on a breaking shape change anywhere in the envelope; additive changes keep the version.
• Tool names (boruna_compile, boruna_run, …) are stable. Renames require a major version bump.
• error_kind values are stable strings. New ones may be added; existing ones are not renamed.
• Top-level response fields (success, protocol_version, named result fields) are stable. New fields are additive.
• Value encoding inside result (the tagged shapes for Option / Result / records / enums) is locked.

Versioning policy for protocol_version

When protocol_version bumps, integrators see protocol_version: 2 (or higher) and can branch on the version to support both shapes during a migration window.

Pairs with Policy.schema_version (currently 1) — together they cover both the request-side policy schema and the response-side envelope.

See also

• policy-schema.md — the structured policy parameter for boruna_run
• policy.schema.json — machine-readable JSON Schema for the same
• cli.md — the matching boruna CLI commands
• AGENTS.md — coding-agent-facing integration guide
• Rust source of record: crates/boruna-mcp/src/server.rs

Edit this page on GitHub

Capability Policy Schema

The policy parameter on the MCP boruna_run tool (and the --policy <file> flag on the boruna CLI) accepts either:

• A string shorthand: "allow-all" or "deny-all"
• A Policy object matching the schema below

This page documents the object form. The machine-readable schema lives at policy.schema.json.

Object form

{
  // Policy schema version. Currently always 1. Optional.
  "schema_version": 1,

  // Default behavior for capabilities NOT listed in `rules`.
  // false = deny by default (allowlist mode); true = allow by default (denylist mode).
  // Required for predictable behavior — do not omit.
  "default_allow": false,

  // Per-capability rules. Keys are capability names (see table below).
  "rules": {
    "net.fetch": {
      "allow":  true,   // boolean, required
      "budget": 0       // u64, required. 0 = unlimited; otherwise hard ceiling on call count.
    }
  },

  // Optional network-specific controls. Applied when `net.fetch` is allowed.
  "net_policy": {
    "allowed_domains":      ["api.openai.com", "*.our-api.example"], // empty = all
    "allowed_methods":      ["GET", "POST"],                          // empty = all
    "max_response_bytes":   10485760,                                 // default 10 MB
    "timeout_ms":           30000,                                    // default 30 s
    "allow_redirects":      true                                      // default true
  }
}

Capability names

These are the strings you use as keys in rules. They mirror boruna_bytecode::Capability::name().

The strict validator rejects aliases. Sprint 0.4-S15 locked the rule-key surface to canonical names only. A policy file with "net" as a rule key fails validation with error_kind: "policy.invalid_capability" and a hint to use "net.fetch". Aliases were silently no-ops at gateway-check time before — fixing that footgun was the point of 0.4-S15 (project convention #1: reject at parse, don’t silently override).

Examples

1. Allowlist domain only — deny everything except net.fetch to api.openai.com

{
  "default_allow": false,
  "rules": { "net.fetch": { "allow": true, "budget": 0 } },
  "net_policy": { "allowed_domains": ["api.openai.com"] }
}

2. Allow-all minus filesystem writes — useful for read-only workflows

{
  "default_allow": true,
  "rules": { "fs.write": { "allow": false, "budget": 0 } }
}

3. LLM call quota — cap LLM invocations at 5 per run

{
  "default_allow": true,
  "rules": { "llm.call": { "allow": true, "budget": 5 } }
}

When the budget is exceeded the run aborts with a runtime_error whose message references CapabilityBudgetExceeded(LlmCall).

Surprising behavior to know

• default_allow defaults to false. A Policy {} (empty object) denies everything. Always set default_allow explicitly.
• budget: 0 means unlimited, not “zero allowed.” Use { "allow": false, "budget": 0 } to deny.
• String shorthand and object form are not mixable. Pass exactly one shape.
• Unknown JSON shapes are rejected. Old MCP clients that accidentally posted typo’d strings (e.g. "alow-all") used to be silently treated as allow-all. They now return success: false, error_kind: "invalid_policy". This is intentional — silent fall-through to allow-all was the bug FleetQ reported.
• Unknown fields are rejected (sprint 0.4-S15). A typo like "default_alow": true no longer parses as default_allow: false (silent default); it fails with error_kind: "policy.unknown_field".
• Unsupported schema_version values are rejected. This binary supports schema_version: 1. Setting 2 or any other value fails with error_kind: "policy.unknown_schema_version".

CLI tooling (sprint 0.4-S15)

# Strict-validate a policy file. Designed as a CI gate.
boruna policy validate policies/prod.json
# → exit 0 + "OK: ..." on success
# → exit 2 + stderr "error: policy.<kind>: ..." on validation error
# → exit 1 + stderr "error: policy.io_error: ..." on file IO error

# Machine-parseable output:
boruna policy validate --json policies/prod.json
# → {"ok":true} or {"ok":false,"errors":[{"error_kind":"policy.unknown_field",...}]}

# Print the effective policy (denormalized).
boruna policy show policies/prod.json

The MCP server exposes the same validator as boruna_policy_validate.

Stable error_kind taxonomy

The strict validator emits these stable strings (project convention #2 — locked forever):

The boruna_run MCP tool also emits the legacy error_kind: "invalid_policy" for non-object input (string typos, arrays, numbers). The new policy.* kinds apply to object-form payloads only — they are additive over invalid_policy, not a replacement.

Versioning

The schema carries schema_version: 1. Future breaking changes will bump this number; the MCP tool will continue to accept the old shape as long as schema_version matches a supported value. This field is what lets you cache (script_hash, policy_hash) results safely across binary upgrades. Sprint 0.4-S15 locked this contract: only 1 is currently accepted; new optional fields can be added at v1; shape changes require a version bump.

Hashing for caching

Because Policy is Serialize + Deserialize, you can hash a normalized policy for cache keys:

#![allow(unused)]
fn main() {
let bytes = serde_json::to_vec(&policy).unwrap();
let hash  = sha2::Sha256::digest(&bytes);
}

Pair hash(policy) with hash(source) to memoize deterministic runs. (The capability-set identity portion — making the hash stable across binary upgrades — is tracked separately in the project roadmap.)

Edit this page on GitHub

Capability Identity & Caching Contract

Boruna binaries advertise a stable, hashable identity for their capability surface. Integrators use this identity to safely cache deterministic run results across binary upgrades.

Stability: stable from 0.3.0. Implementation shipped in 0.2.x for early integrators (FleetQ #3).

Why this exists

Boruna is deterministic by construction: for a given (source, inputs, policy, capability_contract) the run result is identical every time. That means an integrator can memoize results indefinitely — as long as the capability contract hasn’t changed.

Without a stable identity for the capability contract, integrators have two bad options:

1. Don’t cache — leave free determinism on the table.
2. Cache by binary version string — invalidate on every patch release, even when contracts didn’t change.

capability_set_hash solves this: it’s a content-addressed identity over the capability surface that changes only when the contract changes.

Surface

CLI

$ boruna capability list --json
{
  "protocol_version": 1,
  "name": "boruna",
  "version": "0.2.0",
  "capabilities": [
    { "name": "actor.send",   "version": "1" },
    { "name": "actor.spawn",  "version": "1" },
    { "name": "db.query",     "version": "1" },
    { "name": "fs.read",      "version": "1" },
    { "name": "fs.write",     "version": "1" },
    { "name": "llm.call",     "version": "1" },
    { "name": "net.fetch",    "version": "1" },
    { "name": "random",       "version": "1" },
    { "name": "time.now",     "version": "1" },
    { "name": "ui.render",    "version": "1" }
  ],
  "capability_set_hash": "sha256:b0ca1793a79656447d560092bae7af4b0ebee82023c6d2bea82bd80621bd9637"
}

The CLI conveys success via process exit code, so there is no success field.

MCP

Tool boruna_capability_list (no parameters). Returns the same fields as the CLI --json output plus a leading success: true envelope (this server’s universal convention for tool responses):

{
  "success": true,
  "protocol_version": 1,
  "name": "boruna",
  "version": "0.2.0",
  "capabilities": [ ... ],
  "capability_set_hash": "sha256:..."
}

Field semantics

Hash algorithm

The capability_set_hash is computed byte-for-byte as follows:

1. Take all capabilities in canonical order (sorted ascending by name).
2. For each, encode the UTF-8 bytes of "{name}\t{version}\n".
   • \t = ASCII 0x09 (tab)
   • \n = ASCII 0x0A (newline)
3. Concatenate all encodings into a single byte string (no separators between capabilities beyond the trailing \n of each).
4. SHA-256 of that byte string.
5. Lower-case hex, prefixed with "sha256:".

Worked example (current 0.2.0 surface)

The byte string fed to SHA-256 is exactly:

actor.send\t1\nactor.spawn\t1\ndb.query\t1\nfs.read\t1\nfs.write\t1\nllm.call\t1\nnet.fetch\t1\nrandom\t1\ntime.now\t1\nui.render\t1\n

(252 bytes, with literal tabs and newlines, not the escape sequences shown.)

Reproduce with shell:

$ printf 'actor.send\t1\nactor.spawn\t1\ndb.query\t1\nfs.read\t1\nfs.write\t1\nllm.call\t1\nnet.fetch\t1\nrandom\t1\ntime.now\t1\nui.render\t1\n' | shasum -a 256
b0ca1793a79656447d560092bae7af4b0ebee82023c6d2bea82bd80621bd9637  -

Caching contract for integrators

Recommended cache key:

key = sha256(
  source_hash       ||  // sha256(.ax source bytes)
  policy_hash       ||  // sha256(canonical JSON of the Policy object)
  capability_set_hash || // from this endpoint
  policy_schema_version  // from the Policy.schema_version field, e.g. "1"
)

This guarantees:

• A .ax source change invalidates the entry.
• A policy change invalidates the entry.
• A capability contract change invalidates the entry (new capability added, or existing capability semantics changed).
• A policy schema change invalidates the entry (Boruna evolves the policy format).

Anything outside this set — Rust toolchain version, Boruna patch version that didn’t touch capabilities, build host — does not invalidate cached results, because none of it can change the deterministic output.

Per-capability version semantics

Each capability has its own version. We bump it only when the contract changes in a way that would make a downstream cached result invalid:

When you bump a capability version, you must also:

1. Update the match arm in crates/llmbc/src/capability.rs::Capability::version().
2. Update the golden hash in crates/llmbc/src/tests.rs::test_capability_set_hash_known_value.
3. Add a ### Changed entry under [Unreleased] in CHANGELOG.md referencing the capability.

What does and does not affect the hash

This separation is what makes the hash useful: a Boruna patch release that touches no capabilities produces an identical hash, so cached results stay valid.

Stability guarantees

• The algorithm above is frozen. We will never change how the hash is computed without a major version bump (protocol_version: 2) and a clearly-documented migration path. An algorithm-level test (test_compute_capability_set_hash_algorithm_known_value) locks the encoding rule independently of the current capability set.
• The JSON shape of the report is locked at protocol_version: 1. Field additions are non-breaking and keep protocol_version; field removals, renames, or type changes bump protocol_version.
• The per-capability versions evolve independently of each other and of protocol_version. Today they are all "1". Future bumps follow the rules above.

Pairs with Policy.schema_version

The Policy object (see policy schema) carries a schema_version field independently. Together they cover:

• capability_set_hash — does the binary still mean the same thing by net.fetch?
• Policy.schema_version — does the binary still parse my policy the same way?

Both must match for a cached result to be valid.

See also

• docs/reference/policy-schema.md — capability policy structure
• docs/concepts/determinism.md — why Boruna can be cached at all
• FleetQ feedback letter — original ask (issue #3)

Edit this page on GitHub

Diagnostic Codes

Every diagnostic Boruna’s toolchain emits carries a stable E0NN code. Codes are stable forever — never reused, never renumbered. Tools and AI agents may switch on them.

The registry is machine-readable. Query it directly:

boruna lang codes          # human table
boruna lang codes --json   # { "version": 1, "codes": [ ... ] }

Codes appear in boruna lang check --json output as the id field of each diagnostic.

The table above is generated from the same registry the CLI serves (tooling/src/diagnostics/registry.rs). A drift test asserts the registry stays 1:1 with the E0NN constants the compiler emits.

Edit this page on GitHub

Structured Diagnostics + Suggested Patches

Overview

The tooling crate provides machine-readable diagnostics and auto-repair for .ax source files.

Every diagnostic is emitted in two formats:

• Human-readable text (one line per diagnostic)
• Stable JSON (version 1, serializable as diagnostics.json)

Error Codes

Suggested Patches

Each diagnostic may include suggested_patches. Each patch contains:

• id: Stable identifier for this fix
• description: Human-readable summary
• confidence: high, medium, or low
• rationale: Why this fix is suggested
• edits: Array of TextEdit (file, start_line, old_text, new_text)

TextEdits are compatible with the PatchBundle Hunk format.

JSON Format

{
  "version": 1,
  "file": "path/to/file.ax",
  "diagnostics": [
    {
      "id": "E005",
      "severity": "error",
      "message": "non-exhaustive match on 'msg' of type 'Msg': missing variants: Clear, Remove",
      "location": {
        "file": "path/to/file.ax",
        "line": 7,
        "col": null,
        "end_line": null,
        "end_col": null
      },
      "suggested_patches": [
        {
          "id": "E005-add-arms",
          "description": "add missing match arms: Clear, Remove",
          "confidence": "high",
          "rationale": "match expression does not cover variants: Clear, Remove",
          "edits": [
            {
              "file": "path/to/file.ax",
              "start_line": 10,
              "old_text": "    }",
              "new_text": "        Clear => { /* TODO */ }\n        Remove => { /* TODO */ }\n    }"
            }
          ]
        }
      ],
      "related": []
    }
  ]
}

CLI Usage

Check

boruna lang check path/to/file.ax            # human-readable output
boruna lang check path/to/file.ax --json     # JSON to stdout
boruna lang check path/to/file.ax -o diag.json  # JSON to file

Repair

boruna lang repair path/to/file.ax                     # auto-fix with best suggestions
boruna lang repair path/to/file.ax --apply all          # apply all suggestions
boruna lang repair path/to/file.ax --apply E005-add-arms  # apply specific fix
boruna lang repair path/to/file.ax --from diag.json     # use pre-computed diagnostics

Analysis Passes

Match Exhaustiveness (E005)

Detects when a match on a typed enum parameter does not cover all variants. Skips if a wildcard (_) or catch-all identifier pattern is present.

Record Field Validation (E006)

Detects when a record literal uses a field name not present in the type definition. Suggests the closest valid field name via Levenshtein distance.

Capability Purity (E007)

In framework apps (those with init/update/view), detects when update() or view() declare capabilities. Suggests removing the !{...} annotation.

Undefined Variable (E003)

Enhances compiler errors with name suggestions. Collects all defined names (functions, parameters, local variables, types, builtins) and finds the closest match.

Repair Tool

The repair tool:

1. Reads diagnostics (from JSON or runs check)
2. Selects patches based on strategy (best/all/specific ID)
3. Applies text edits to the source (reverse line order to avoid offset drift)
4. Re-runs diagnostics to verify the fix
5. Reports before/after diagnostic count and verify status

Patches are applied deterministically: same input always produces the same output.

Edit this page on GitHub

Canonical error_kind taxonomy

This is the single source of truth for the stable error_kind strings emitted by the Boruna binary and the MCP server.

Stability contract

• These strings are stable per docs/lts.md §B.6 (“Error taxonomy”). Once shipped in a tag, an error_kind is never renamed or removed inside the 1.x line.
• New error_kind values MAY be added in 1.x minor releases; integrators MUST tolerate values they don’t recognize.
• Integrators MAY switch on these strings programmatically — the strings are part of the LTS-protected contract, not human-readable log copy.

How this list is maintained

Every entry below is verified against a literal-string grep of the crates/ and orchestrator/ trees. When a new error_kind is added to the source, it MUST be added here in the same change. CI may grow a gate for this in a future sprint; today the discipline is reviewer- enforced.

evidence.* — evidence bundle reader

Emitted by boruna evidence verify and boruna evidence inspect. See orchestrator/src/audit/encryption.rs::EncryptionError for the source strings.

Note on the W1-C reader gate. Bundles missing bundle.json or carrying an incompatible major format_version are rejected by verify_bundle with the diagnostic unsupported evidence bundle format_version: found '<x>', expected major '<y>'. This message is emitted as a VerifyError, not as a JSON error_kind field; tools wrapping the reader translate it to their own taxonomy. See orchestrator/src/audit/verify.rs::VerifyError.

workflow.* — workflow JSON definition reader

Emitted by boruna_orchestrator::WorkflowDef::from_json and surfaces in boruna workflow validate / boruna workflow run / the coord POST /api/runs path.

policy.* — policy schema validator

Emitted by boruna policy validate and boruna_run (object-form policy input). See docs/reference/policy-schema.md for full context.

MCP-layer top-level kinds

Emitted by the boruna-mcp server’s tool layer. These predate the namespaced evidence.* / workflow.* schemes and are kept for back-compat per the LTS contract.

Conventions

• All error_kind strings are dotted, lower-snake-case, and hierarchical (<namespace>.<short_kind>). The namespace identifies the surface (evidence reader, workflow loader, policy validator, MCP top-level).
• “Phase” follows the project convention of distinguishing serialization (parse-time / shape rejection) from output_validation (post-execution shape rejection) from execution (runtime failures). N/A means the kind is a control-flow / policy-gate decision rather than a shape error.

Cross-references

• docs/lts.md §B.6 — LTS commitment for error_kind strings.
• docs/reference/policy-schema.md — full policy validator surface.
• docs/reference/cli.md — CLI surface; CLI errors are printed in error_kind: <kind> form on stderr.
• docs/spec/evidence-bundle-1.0.md §8 — evidence bundle encryption reader contract (source of evidence.*).
• docs/spec/workflow-dag-1.0.md — workflow DAG schema (source of workflow.*).

Edit this page on GitHub

Framework Public API

Stability: Experimental within the Boruna 1.x line. The framework is the Elm-architecture runtime exposed by boruna_framework; it ships with the rest of Boruna under the workspace version (currently v1.0.0-rc2) but its public types are NOT included in the LTS contract §B. Expect API changes between Boruna 1.x minor releases as adoption feedback comes in. See stability.md for the tier definitions and lts.md for the surfaces that ARE LTS-protected.

All unlisted types/functions are internal and may change without notice.

boruna_framework (crate root re-exports)

#![allow(unused)]
fn main() {
pub use error::FrameworkError;
pub use runtime::AppRuntime;
pub use validate::AppValidator;
pub use testing::TestHarness;
pub use policy::PolicySet;
}

boruna_framework::error

#![allow(unused)]
fn main() {
pub enum FrameworkError {
    Validation(String),
    MissingFunction(String),
    PurityViolation { name: String },
    WrongArity { name: String, expected: usize, got: usize },
    MissingType(String),
    Effect(String),
    PolicyViolation(String),
    State(String),
    Compile(boruna_compiler::CompileError),
    Runtime(boruna_vm::VmError),
    MaxCyclesExceeded(u64),
}
}

boruna_framework::validate

#![allow(unused)]
fn main() {
pub struct AppValidator;

impl AppValidator {
    pub fn validate(program: &Program) -> Result<ValidationResult, FrameworkError>;
    pub fn is_valid_app(program: &Program) -> bool;
}

pub struct ValidationResult {
    pub has_init: bool,
    pub has_update: bool,
    pub has_view: bool,
    pub has_policies: bool,
    pub state_type: Option<String>,
    pub message_type: Option<String>,
    pub errors: Vec<String>,
}
}

boruna_framework::runtime

#![allow(unused)]
fn main() {
pub struct AppMessage {
    pub tag: String,
    pub payload: Value,
}

impl AppMessage {
    pub fn new(tag: impl Into<String>, payload: Value) -> Self;
    pub fn to_value(&self) -> Value;
}

pub struct CycleRecord {
    pub cycle: u64,
    pub message: AppMessage,
    pub state_before: Value,
    pub state_after: Value,
    pub effects: Vec<Effect>,
    pub ui_tree: Option<Value>,
}

pub struct AppRuntime { /* private fields */ }

impl AppRuntime {
    pub fn new(module: Module) -> Result<Self, FrameworkError>;
    pub fn state(&self) -> &Value;
    pub fn cycle(&self) -> u64;
    pub fn cycle_log(&self) -> &[CycleRecord];
    pub fn policy(&self) -> &PolicySet;
    pub fn state_machine(&self) -> &StateMachine;
    pub fn send(&mut self, msg: AppMessage) -> Result<(Value, Vec<Effect>, Option<Value>), FrameworkError>;
    pub fn view(&self) -> Result<Value, FrameworkError>;
    pub fn snapshot(&self) -> String;
    pub fn rewind(&mut self, cycle: u64) -> Result<(), FrameworkError>;
    pub fn diff_from(&self, cycle: u64) -> Vec<StateDiff>;
}
}

boruna_framework::effect

#![allow(unused)]
fn main() {
pub struct Effect {
    pub kind: EffectKind,
    pub payload: Value,
    pub callback_tag: String,
}

pub enum EffectKind {
    HttpRequest, DbQuery, FsRead, FsWrite,
    Timer, Random, SpawnActor, EmitUi,
}

impl EffectKind {
    pub fn from_str(s: &str) -> Option<Self>;
    pub fn capability_name(&self) -> &'static str;
    pub fn as_str(&self) -> &'static str;
}

pub fn parse_effects(effects_value: &Value) -> Vec<Effect>;
pub fn parse_update_result(value: &Value) -> Option<(Value, Vec<Effect>)>;
}

boruna_framework::state

#![allow(unused)]
fn main() {
pub struct StateSnapshot {
    pub cycle: u64,
    pub state: Value,
    pub json: String,
}

pub struct StateDiff {
    pub field_index: usize,
    pub field_name: String,
    pub old_value: Value,
    pub new_value: Value,
}

pub struct StateMachine { /* private fields */ }

impl StateMachine {
    pub fn new(initial_state: Value) -> Self;
    pub fn current(&self) -> &Value;
    pub fn cycle(&self) -> u64;
    pub fn history(&self) -> &[StateSnapshot];
    pub fn transition(&mut self, new_state: Value);
    pub fn snapshot(&self) -> String;
    pub fn restore(&mut self, json: &str) -> Result<(), FrameworkError>;
    pub fn diff_from_cycle(&self, cycle: u64) -> Vec<StateDiff>;
    pub fn diff_values(old: &Value, new: &Value) -> Vec<StateDiff>;
    pub fn rewind(&mut self, target_cycle: u64) -> Result<(), FrameworkError>;
}
}

boruna_framework::ui

#![allow(unused)]
fn main() {
pub struct UINode {
    pub tag: String,
    pub props: Vec<(String, Value)>,
    pub children: Vec<UINode>,
}

impl UINode {
    pub fn new(tag: impl Into<String>) -> Self;
    pub fn with_prop(self, key: impl Into<String>, value: Value) -> Self;
    pub fn with_child(self, child: UINode) -> Self;
}

pub fn value_to_ui_tree(value: &Value) -> UINode;
pub fn ui_tree_to_value(node: &UINode) -> Value;
}

boruna_framework::policy

#![allow(unused)]
fn main() {
pub struct PolicySet {
    pub capabilities: Vec<String>,
    pub max_effects_per_cycle: u64,
    pub max_steps: u64,
}

impl PolicySet {
    pub fn allow_all() -> Self;
    pub fn from_value(value: &Value) -> Self;
    pub fn check_effect(&self, effect: &Effect) -> Result<(), FrameworkError>;
    pub fn check_batch(&self, effects: &[Effect]) -> Result<(), FrameworkError>;
}
}

boruna_framework::testing

#![allow(unused)]
fn main() {
pub struct TestHarness { /* private fields */ }

impl TestHarness {
    pub fn from_source(source: &str) -> Result<Self, FrameworkError>;
    pub fn state(&self) -> &Value;
    pub fn cycle(&self) -> u64;
    pub fn send(&mut self, msg: AppMessage) -> Result<(Value, Vec<Effect>), FrameworkError>;
    pub fn simulate(&mut self, messages: Vec<AppMessage>) -> Result<Value, FrameworkError>;
    pub fn assert_state_field(field_index: usize, expected: &Value) -> Result<(), FrameworkError>;
    pub fn assert_effects(expected_kinds: &[&str]) -> Result<(), FrameworkError>;
    pub fn assert_state(expected: &Value) -> Result<(), FrameworkError>;
    pub fn cycle_log(&self) -> &[CycleRecord];
    pub fn snapshot(&self) -> String;
    pub fn rewind(&mut self, cycle: u64) -> Result<(), FrameworkError>;
    pub fn replay_verify(&self, source: &str, messages: Vec<AppMessage>) -> Result<bool, FrameworkError>;
    pub fn view(&self) -> Result<Value, FrameworkError>;
    pub fn runtime(&self) -> &AppRuntime;
}

pub fn simulate_messages(source: &str, messages: Vec<AppMessage>) -> Result<Value, FrameworkError>;
}

Edit this page on GitHub

Compliance Workflow Templates

Pre-built workflow patterns for common regulated use cases. Each template demonstrates how Boruna’s evidence bundle, capability policy, and approval gate features satisfy specific compliance requirements.

How to use

1. Copy the template to your project
2. Replace synthetic data with real capability calls (e.g., net.fetch for live system data)
3. Run with --record to produce a verifiable evidence bundle:

   boruna workflow run examples/compliance/soc2_audit_workflow --policy allow-all --record
   boruna evidence verify <bundle-dir>
   

4. The verified bundle is your compliance artifact

Customisation

Each template README describes which steps to modify for your environment. Real integrations typically replace the gather_* or receive_* first step with a capability call to fetch live data.

Edit this page on GitHub

std-authz

Role and permission enforcement via policies

Package: std.authz Version: 0.1.0 Capabilities required: none

Overview

std-authz provides a simple, policy-driven authorization model based on named roles and numeric privilege levels. Call authz_check in your update handler before applying any state change that requires a permission gate. Because all functions are pure and deterministic, authorization decisions are fully auditable and replayable from the evidence bundle.

Installation

Add to your package.ax.json dependencies:

"std.authz": "0.1.0"

API Reference

Types

AuthzPolicy

type AuthzPolicy {
    admin_role: String,
    editor_role: String,
    viewer_role: String,
    admin_level: Int,
    editor_level: Int,
    viewer_level: Int
}

Maps role names to numeric privilege levels. Higher levels have broader access.

Role

type Role { name: String, level: Int }

Permission

type Permission { resource: String, action: String }

RolePermission

type RolePermission { role_name: String, resource: String, action: String }

AuthzResult

type AuthzResult { allowed: Int, reason: String }

• allowed — 1 if the operation is permitted, 0 if denied
• reason — human-readable explanation for logging

Functions

authz_default_policy() -> AuthzPolicy

Returns the built-in three-tier policy: admin (level 100), editor (level 50), viewer (level 10).

authz_check(policy: AuthzPolicy, role_name: String, resource: String, action: String) -> AuthzResult

The primary authorization gate. Checks whether role_name is permitted to perform action on resource.

Supported actions: "read" (requires viewer+), "write" (requires editor+), "delete" (requires admin).

Parameters

• policy — the active AuthzPolicy
• role_name — the principal’s role string
• resource — the resource being accessed (informational; used for the reason message)
• action — "read", "write", or "delete"

Returns — AuthzResult with allowed: 1 or allowed: 0 and a descriptive reason.

Example

fn main() -> Int {
  let policy: AuthzPolicy = authz_default_policy()
  let result: AuthzResult = authz_check(policy, "editor", "documents", "write")
  result.allowed
}

authz_require_role(policy: AuthzPolicy, role_name: String, min_level: Int) -> AuthzResult

Returns allowed if the role’s numeric level meets or exceeds min_level. Useful for custom thresholds beyond the three built-in actions.

authz_role_level(policy: AuthzPolicy, role_name: String) -> Int

Returns the numeric privilege level for a role name. Returns 0 for unknown roles.

authz_guard_update(policy: AuthzPolicy, role_name: String, resource: String, action: String) -> Int

Convenience wrapper that calls authz_check and returns only the allowed integer — handy in if guards.

authz_is_admin(policy: AuthzPolicy, role_name: String) -> Int

Returns 1 if role_name matches the policy’s admin role.

authz_can_write(policy: AuthzPolicy, role_name: String) -> Int

Returns 1 if the role has editor-level or higher privileges.

authz_can_read(policy: AuthzPolicy, role_name: String) -> Int

Returns 1 if the role has viewer-level or higher privileges.

Capabilities

None. All functions are pure predicates with no side effects.

Notes / Limitations

• The policy is a fixed three-role structure. Custom roles beyond admin/editor/viewer can be checked via authz_require_role with an explicit min_level.
• Role names are compared by string equality; casing matters.
• resource is passed through to the reason string but is not used in access-control logic — access depends solely on the action and role level.

Edit this page on GitHub

std-db

Typed database query helpers

Package: std.db Version: 0.1.0 Capabilities required: db.query

Overview

std-db provides a builder API for constructing typed database queries and converting them to Effect values for execution. Build a Query with the CRUD helpers, refine it with db_where, db_order, and db_paginate, then call db_to_effect to hand it off to the runtime. The library also includes a Pagination type and helpers for navigating paged result sets.

Installation

Add to your package.ax.json dependencies:

"std.db": "0.1.0"

Your policy must grant db.query.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

Query

type Query {
    operation: String,
    table: String,
    columns: String,
    conditions: String,
    order_by: String,
    limit_val: Int,
    offset_val: Int
}

A portable query descriptor. columns is a comma-separated list; conditions is a raw filter expression string.

Pagination

type Pagination { page: Int, per_page: Int, total: Int, total_pages: Int }

Computed pagination metadata. Use with pagination_has_next / pagination_has_prev in your view.

Functions

Query builders

db_select(table: String, columns: String) -> Query

Creates a SELECT query for the specified columns.

Example

fn main() -> Int {
  let q: Query = db_select("users", "id, name, email")
  let q2: Query = db_where(q, "active = 1")
  let q3: Query = db_order(q2, "name")
  let q4: Query = db_paginate(q3, 1, 20)
  let eff: Effect = db_to_effect(q4, "users_loaded")
  0
}

db_insert(table: String, columns: String, values: String) -> Query

Creates an INSERT query. columns and values are comma-separated strings corresponding to each other positionally.

db_update(table: String, sets: String, conditions: String) -> Query

Creates an UPDATE query. sets is a comma-separated list of column = value assignments.

db_delete(table: String, conditions: String) -> Query

Creates a DELETE query filtered by conditions.

Query modifiers

db_where(query: Query, condition: String) -> Query

Replaces the query’s condition expression. Call after the initial builder.

db_order(query: Query, column: String) -> Query

Sets the ORDER BY column.

db_limit(query: Query, limit_val: Int) -> Query

Sets a row limit.

db_offset(query: Query, offset_val: Int) -> Query

Sets a row offset.

db_paginate(query: Query, page: Int, per_page: Int) -> Query

Sets limit_val and offset_val from a 1-based page number and page size. Equivalent to calling db_limit and db_offset with the computed values.

Effect dispatch

db_to_effect(query: Query, callback_tag: String) -> Effect

Converts a Query to an Effect with kind: "db_query". Return this from update to execute the query.

Pagination helpers

pagination_info(page: Int, per_page: Int, total: Int) -> Pagination

Computes the Pagination record from a known total row count.

pagination_has_next(p: Pagination) -> Int

Returns 1 if there is a next page.

pagination_has_prev(p: Pagination) -> Int

Returns 1 if there is a previous page.

pagination_next_page(p: Pagination) -> Int

Returns the next page number, or the current page if already at the last.

pagination_prev_page(p: Pagination) -> Int

Returns the previous page number, or 1 if already at the first.

Capabilities

Requires db.query. Queries are executed by the runtime’s capability handler; the library itself produces only data structures.

Notes / Limitations

• Condition strings (conditions, sets) are passed through verbatim to the runtime. The library does not perform sanitization; callers are responsible for safe parameterization.
• db_paginate uses 1-based page numbers. Page 0 or negative values produce a negative offset.
• total_pages is computed as ceil(total / per_page); when total == 0 the result is 1.

Edit this page on GitHub

std-forms

Model-driven form engine with validation and state tracking

Package: std.forms Version: 0.1.0 Capabilities required: none

Overview

std-forms manages the lifecycle of multi-field forms inside framework apps. It provides two complementary state types — FieldState for individual inputs and FormState for the whole form — and a set of pure functions to transition between them. Use it in your update(State, Msg) -> UpdateResult handler to track dirty/touched flags, field errors, and submission state without writing that boilerplate yourself.

std-forms depends on std.validation for composable rule checking.

Installation

Add to your package.ax.json dependencies:

"std.forms": "0.1.0"

std.validation is pulled in automatically as a transitive dependency.

API Reference

Types

FieldState

type FieldState { name: String, value: String, touched: Int, dirty: Int, error: String }

• touched — 1 if the user has focused the field at least once
• dirty — 1 if the value has changed from its initial state
• error — current validation error message, or "" when valid

FormState

type FormState {
    field_count: Int,
    submitted: Int,
    valid: Int,
    current_field: String,
    current_value: String,
    current_error: String
}

• submitted — 1 after a successful form_submit
• valid — 0 as soon as any field error is set; reset by form_clear_errors

Functions

Form lifecycle

form_init(field_count: Int) -> FormState

Creates a fresh form. Pass the number of fields to pre-declare capacity.

form_set_field(form: FormState, name: String, value: String) -> FormState

Records the most-recently changed field name and value. Call this on every input change message.

form_set_error(form: FormState, field: String, error: String) -> FormState

Attaches a validation error to a named field and marks the form invalid.

form_clear_errors(form: FormState) -> FormState

Clears all errors and resets valid to 1.

form_submit(form: FormState) -> FormState

Transitions the form to the submitted state if valid == 1. No-ops if the form is invalid.

form_reset(form: FormState) -> FormState

Resets all fields to their initial state while preserving field_count.

Form predicates

form_is_valid(form: FormState) -> Int

Returns 1 if no errors are set.

form_is_submitted(form: FormState) -> Int

Returns 1 after a successful submission.

Field lifecycle

field_init(name: String) -> FieldState

Creates a fresh field with an empty value and no errors.

field_set_value(field: FieldState, value: String) -> FieldState

Updates the field value and marks it dirty.

field_touch(field: FieldState) -> FieldState

Marks the field as touched (user has interacted with it).

field_set_error(field: FieldState, error: String) -> FieldState

Attaches a validation error message.

field_clear_error(field: FieldState) -> FieldState

Clears any error message.

field_is_valid(field: FieldState) -> Int

Returns 1 if the field has no error.

field_reset(field: FieldState) -> FieldState

Resets to empty, untouched, and error-free while keeping the field name.

Example

fn main() -> Int {
  let form: FormState = form_init(2)
  let name_field: FieldState = field_init("name")
  let name_typed: FieldState = field_set_value(name_field, "Alice")
  let name_visited: FieldState = field_touch(name_typed)
  let form2: FormState = form_set_field(form, "name", "Alice")
  let result: FormState = form_submit(form2)
  result.submitted
}

Capabilities

None. All state transitions are pure functions.

Notes / Limitations

• FormState stores only the most-recently changed field. Apps with multiple fields should maintain per-field FieldState values in their own State record and use FormState for overall validity and submission tracking.
• field_count is informational only; the engine does not iterate over fields.

Edit this page on GitHub

std-http

Safe typed HTTP effect wrappers

Package: std.http Version: 0.1.0 Capabilities required: net.fetch

Overview

std-http wraps outbound HTTP calls as typed Effect values. Your update handler returns these effects; the Boruna runtime dispatches them through the net.fetch capability and delivers responses back via the named callback_tag. This keeps network I/O out of pure logic and makes every request auditable in the evidence bundle. The library also provides retry configuration helpers and status-code predicates.

Installation

Add to your package.ax.json dependencies:

"std.http": "0.1.0"

Your workflow or app policy must grant net.fetch to the step that uses this library.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

Returned by all request-building functions. Pass it back from update to trigger the HTTP call.

HttpRequest

type HttpRequest { method: String, url: String, body: String, content_type: String }

A fully described request for use with http_request.

HttpResponse

type HttpResponse { status: Int, body: String }

Shape of the response delivered to the callback_tag handler.

RetryConfig

type RetryConfig { max_retries: Int, backoff_ms: Int, multiplier: Int }

Exponential backoff parameters used with http_next_backoff.

Functions

Request builders

http_get(url: String, callback_tag: String) -> Effect

Produces a GET request effect.

Example

fn main() -> Int {
  let eff: Effect = http_get("https://api.example.com/items", "items_loaded")
  0
}

http_post(url: String, body: String, callback_tag: String) -> Effect

Produces a POST request effect with the given body.

http_put(url: String, body: String, callback_tag: String) -> Effect

Produces a PUT request effect.

http_delete(url: String, callback_tag: String) -> Effect

Produces a DELETE request effect.

http_request(req: HttpRequest, callback_tag: String) -> Effect

Produces an effect from a fully specified HttpRequest — use when you need to set content_type or other fields explicitly.

Retry helpers

http_default_retry() -> RetryConfig

Returns a sensible default: 3 retries, 1000 ms base backoff, multiplier 2.

http_retry_config(max_retries: Int, backoff_ms: Int, multiplier: Int) -> RetryConfig

Constructs a custom retry configuration.

http_next_backoff(config: RetryConfig, attempt: Int) -> Int

Returns the wait duration in milliseconds before the next retry for a given attempt index (0-based). Uses fixed exponential steps up to attempt == 2; subsequent attempts cap at backoff_ms * multiplier^2.

Status-code predicates

http_is_success(status: Int) -> Int

Returns 1 for 2xx status codes.

http_is_error(status: Int) -> Int

Returns 1 for 4xx and 5xx status codes.

http_should_retry(status: Int) -> Int

Returns 1 for status 429 (Too Many Requests) or any 5xx — the conditions under which retrying is appropriate.

http_parse_status(payload: String) -> Int

Parses a status code string to Int. Returns 0 if parsing fails.

Capabilities

Requires net.fetch. The VM’s CapabilityGateway enforces this at runtime; the call is rejected if the active policy does not include net.fetch.

Notes / Limitations

• All functions produce Effect values — they do not perform any I/O themselves. Actual network calls happen in the runtime after the update function returns.
• http_next_backoff implements three-step exponential backoff only. If attempt >= 3 the backoff is not further increased in the current implementation.
• http_parse_status is a stub that returns 0; the runtime is expected to set the status field directly on the response record delivered to the callback.

Edit this page on GitHub

std-json

JSON-flavoured data extraction and manipulation utilities

Package: std.json Version: 0.1.0 Capabilities required: none

Overview

std-json provides pure-functional helpers for building JSON-formatted strings from typed Boruna values. It covers the four JSON scalar types (string, number, boolean, null), object wrapping, and array wrapping. Because it has no capability requirements it can be used in any step regardless of policy. All functions are deterministic and produce no side effects.

Installation

Add to your package.ax.json dependencies:

"std.json": "0.1.0"

No capability grants are required.

API Reference

Types

JsonResult

type JsonResult { ok: Bool, value: String, error: String }

A tagged result for operations that may fail. When ok is true, value holds the result; when false, error holds the reason.

Functions

Result constructors

json_ok(value: String) -> JsonResult

Wraps a successful string result in a JsonResult with ok = true.

json_err(error: String) -> JsonResult

Wraps an error message in a JsonResult with ok = false.

Field serialisers

json_string_field(key: String, value: String) -> String

Returns a JSON key-value fragment for a string value: "key": "value".

Example

fn main() -> Int {
  let field: String = json_string_field("name", "Alice")
  // field == "\"name\": \"Alice\""
  let obj: String = json_object(field)
  // obj == "{\"name\": \"Alice\"}"
  0
}

json_int_field(key: String, value: Int) -> String

Returns a JSON key-value fragment for an integer value: "key": <n>.

json_bool_field(key: String, value: Bool) -> String

Returns a JSON key-value fragment for a boolean value: "key": true or "key": false.

json_null_field(key: String) -> String

Returns a JSON key-value fragment for a null value: "key": null.

Container builders

json_object(fields: String) -> String

Wraps a pre-serialised fields string in {...}. Combine multiple fields with string concatenation before passing.

json_array_wrap(items: String) -> String

Wraps a pre-serialised items string in [...].

Utilities

json_escape(s: String) -> String

Escapes a string for safe inclusion in a JSON value. Correctly escapes " and \ characters.

int_to_string(n: Int) -> String

Converts an integer to its decimal string representation. Wraps __builtin_int_to_string.

Capabilities

None. std-json is pure-functional with no side effects.

Notes

• There is no recursive structure support; callers must build nested JSON by concatenating field strings manually before passing to json_object.

Version History

Edit this page on GitHub

std-llm

Typed LLM effect wrappers for prompting and structured generation

Package: std.llm Version: 0.1.0 Capabilities required: llm.call

Overview

std-llm wraps LLM calls as typed Effect values. Your update handler returns these effects; the Boruna runtime dispatches them through the llm.call capability and delivers responses back via the named callback_tag. This keeps model I/O out of pure logic and makes every prompt auditable in the evidence bundle. Temperature is stored as Int * 100 (e.g. 72 = 0.72) to avoid floating-point precision issues.

Installation

Add to your package.ax.json dependencies:

"std.llm": "0.1.0"

Your workflow or app policy must grant llm.call to the step that uses this library.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

Returned by all request-building functions. Pass it back from update to trigger the LLM call. kind is either "llm_call" or "llm_json_call".

LlmRequest

type LlmRequest { system_prompt: String, user_prompt: String, max_tokens: Int, temperature: Int }

A fully described request for use with llm_call or llm_json_call. temperature is Int * 100 (e.g. 72 = 0.72).

LlmResponse

type LlmResponse { content: String, tokens_used: Int, finish_reason: String }

Shape of the response delivered to the callback_tag handler.

Functions

llm_prompt(system: String, user: String, callback_tag: String) -> Effect

Convenience function: builds a default LlmRequest (1024 max tokens, temperature 0.72) and emits an "llm_call" effect.

Example

fn main() -> Int {
  let eff: Effect = llm_prompt(
    "You are a helpful assistant.",
    "Summarize this document.",
    "summary_done"
  )
  0
}

llm_call(req: LlmRequest, callback_tag: String) -> Effect

Emits an "llm_call" effect from a fully specified LlmRequest — use when you need to control max_tokens or temperature explicitly.

llm_json_call(req: LlmRequest, callback_tag: String) -> Effect

Emits an "llm_json_call" effect, signalling to the runtime that the model should be prompted for structured JSON output.

default_llm_request(system: String, user: String) -> LlmRequest

Constructs an LlmRequest with default values: max_tokens = 1024, temperature = 72. Use when you want to inspect or mutate the request before passing it to llm_call.

Capabilities

Requires llm.call. The VM’s CapabilityGateway enforces this at runtime; the call is rejected if the active policy does not include llm.call.

Notes / Limitations

• All functions produce Effect values — they do not perform any I/O themselves. Actual model calls happen in the runtime after the update function returns.
• temperature is encoded as Int * 100; 72 means 0.72. There is no float conversion in-language.
• The payload field of the produced Effect is system_prompt ++ "|" ++ user_prompt; the runtime splits on | to reconstruct the two prompts.

Version History

Edit this page on GitHub

std-notifications

Notification queue and toast helpers

Package: std.notifications Version: 0.1.0 Capabilities required: time.now

Overview

std-notifications manages a bounded in-memory queue of toast-style notifications. Add messages with the level-specific helpers (notification_success, notification_error, etc.), dismiss them by ID, and schedule auto-dismiss timers with notification_dismiss_effect. All queue management is pure; only auto-dismiss produces a timer Effect.

Installation

Add to your package.ax.json dependencies:

"std.notifications": "0.1.0"

Your policy must grant time.now if you use notification_dismiss_effect.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

Notification

type Notification { id: Int, level: String, message: String, dismiss_ms: Int }

• id — unique monotonic integer assigned at push time
• level — "info", "success", "warning", or "error"
• dismiss_ms — milliseconds until auto-dismiss; 0 means no auto-dismiss

NotificationQueue

type NotificationQueue {
    next_id: Int,
    count: Int,
    max_visible: Int,
    last_level: String,
    last_message: String,
    last_id: Int
}

• next_id — the ID that will be assigned to the next pushed notification
• count — number of currently visible notifications
• max_visible — cap beyond which new pushes should be blocked or the oldest dropped
• last_level / last_message / last_id — fields of the most recently pushed notification

Functions

Initialization

notification_init(max_visible: Int) -> NotificationQueue

Creates an empty queue with the given visible-notification cap.

Pushing notifications

notification_info(queue: NotificationQueue, level: String, message: String) -> NotificationQueue

Pushes a notification with level "info" and dismiss_ms: 3000.

notification_success(queue: NotificationQueue, message: String) -> NotificationQueue

Pushes a success notification with dismiss_ms: 3000.

notification_warning(queue: NotificationQueue, message: String) -> NotificationQueue

Pushes a warning notification with dismiss_ms: 5000.

notification_error(queue: NotificationQueue, message: String) -> NotificationQueue

Pushes an error notification with dismiss_ms: 0 (sticky — does not auto-dismiss).

notification_push(queue: NotificationQueue, level: String, message: String, dismiss_ms: Int) -> NotificationQueue

Low-level push with explicit level and dismiss duration.

Example

fn main() -> Int {
  let q: NotificationQueue = notification_init(5)
  let q1: NotificationQueue = notification_success(q, "Changes saved")
  let q2: NotificationQueue = notification_error(q1, "Upload failed")
  q2.count
}

Constructing a notification record

notification_make(id: Int, level: String, message: String, dismiss_ms: Int) -> Notification

Constructs a Notification value directly. Use when rendering the queue in your view.

Dismissing

notification_dismiss(queue: NotificationQueue, id: Int) -> NotificationQueue

Decrements count by one. The id parameter is informational; the implementation does not track individual items in the current version.

notification_dismiss_effect(id: Int, delay_ms: Int) -> Effect

Produces a timer effect that fires after delay_ms milliseconds. Wire the "notification_dismissed" callback to call notification_dismiss in your update handler.

Predicates

notification_count(queue: NotificationQueue) -> Int

Returns the current number of visible notifications.

notification_is_full(queue: NotificationQueue) -> Int

Returns 1 if count >= max_visible.

Capabilities

time.now is required for the timer effect produced by notification_dismiss_effect. Queue-management functions are pure and need no capability.

Notes / Limitations

• The queue does not store individual Notification records internally. last_id, last_level, and last_message reflect only the most recently pushed item. To render all visible notifications your app state should maintain a list of Notification values alongside the NotificationQueue.
• notification_dismiss decrements the count without validating the id. Calling it more times than there are visible notifications will clamp at 0.
• Auto-dismiss (dismiss_ms > 0) requires your update handler to return the timer effect and handle the "notification_dismissed" callback.

Edit this page on GitHub

std-routing

Declarative routing model

Package: std.routing Version: 0.1.0 Capabilities required: none

Overview

std-routing gives framework apps a lightweight, deterministic routing layer. Routes are declared as Route records, and matching is done with pure functions — no parsing magic, no global history object. Define your routes once, call route_match_first in your update handler when the path changes, and use route_is_active in your view to highlight the current link.

Installation

Add to your package.ax.json dependencies:

"std.routing": "0.1.0"

API Reference

Types

Route

type Route { name: String, path: String, param_count: Int }

• name — a stable identifier used throughout the app (e.g. "home", "users")
• path — the URL path string to match against (e.g. "/", "/users")
• param_count — number of dynamic parameters in the path (0 for static routes)

RouteMatch

type RouteMatch { matched: Int, route_name: String, param1: String, param2: String }

• matched — 1 if a route matched, 0 otherwise
• route_name — the name of the matched route, "" on no match
• param1 / param2 — extracted path parameters (up to two)

Functions

route_define(name: String, path: String) -> Route

Declares a static route with no dynamic parameters.

Example

fn main() -> Int {
  let home: Route = route_define("home", "/")
  let users: Route = route_define("users", "/users")
  let settings: Route = route_define("settings", "/settings")
  let m: RouteMatch = route_match_first(home, users, settings, "/users")
  m.matched
}

route_define_with_param(name: String, path: String, param_count: Int) -> Route

Declares a route that expects param_count dynamic path segments.

route_match_path(route: Route, path: String) -> RouteMatch

Checks a single route against path. Returns a no-match result if route.path != path.

route_match_first(r1: Route, r2: Route, r3: Route, path: String) -> RouteMatch

Tries r1, r2, and r3 in order and returns the first match. Returns the result of r3 (which may be a no-match) if none of the first two matched. Use as a three-entry router table.

route_no_match() -> RouteMatch

Returns a zero-value no-match result. Use as a fallback or default.

route_navigate(route_name: String) -> String

Returns the route name as a navigation token. The framework dispatches this to the runtime to push the new path.

route_navigate_with_param(route_name: String, param: String) -> String

Like route_navigate but carries a single parameter.

route_is_active(current_route: String, route_name: String) -> Int

Returns 1 if current_route == route_name. Use in view to highlight active navigation links.

Capabilities

None. All functions are pure.

Notes / Limitations

• route_match_path uses exact string equality. Dynamic path segments (e.g. /users/42) require the calling app to extract parameters before matching, or use param_count as a hint to implement custom segment splitting.
• route_match_first handles exactly three routes. For larger route tables, nest calls or use a series of route_match_path checks in your update handler.
• route_navigate returns the route name string as a navigation token; the actual URL push is performed by the runtime, not the library.

Edit this page on GitHub

std-storage

Typed local persistence abstraction

Package: std.storage Version: 0.1.0 Capabilities required: fs.read, fs.write

Overview

std-storage provides a namespaced key-value persistence layer as Effect values. Operations are described purely at the .ax level; actual I/O happens in the Boruna runtime. Entries carry a monotonic version counter which makes conflict detection straightforward and keeps all storage operations fully replay-compatible.

Installation

Add to your package.ax.json dependencies:

"std.storage": "0.1.0"

Your policy must grant both fs.read and fs.write.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

StorageKey

type StorageKey { namespace: String, key: String }

A typed composite key. The namespace scopes keys to a logical bucket (e.g. "app", "cache").

StorageEntry

type StorageEntry { namespace: String, key: String, value: String, version: Int }

A versioned key-value record. value is stored as a JSON string by convention. version is a monotonic integer incremented by storage_bump_version.

Functions

Key construction

storage_key(namespace: String, key: String) -> StorageKey

Constructs a typed key. Useful for passing keys around without losing the namespace.

Effect builders

storage_get(namespace: String, key: String, callback_tag: String) -> Effect

Produces a read effect. The runtime delivers the stored value to callback_tag.

Example

fn main() -> Int {
  let eff: Effect = storage_get("app", "settings", "settings_loaded")
  0
}

storage_set(namespace: String, key: String, value: String, callback_tag: String) -> Effect

Produces a write effect. value is written at the given key.

storage_delete(namespace: String, key: String, callback_tag: String) -> Effect

Produces a delete effect. The key is removed from the namespace.

storage_list(namespace: String, callback_tag: String) -> Effect

Produces a list effect. The runtime delivers all keys in the namespace to callback_tag.

Entry helpers

storage_make_entry(namespace: String, key: String, value: String, version: Int) -> StorageEntry

Constructs a StorageEntry with an explicit version. Use when deserializing a stored entry.

storage_bump_version(entry: StorageEntry, new_value: String) -> StorageEntry

Returns a new entry with value updated and version incremented by one.

Example: optimistic update

fn main() -> Int {
  let entry: StorageEntry = storage_make_entry("app", "counter", "0", 1)
  let updated: StorageEntry = storage_bump_version(entry, "1")
  updated.version
}

storage_is_newer(a: StorageEntry, b: StorageEntry) -> Int

Returns 1 if a.version > b.version. Use for last-write-wins conflict resolution.

Capabilities

Requires fs.read for read/list operations and fs.write for write/delete operations. The capabilities are enforced separately — a step that only reads can be granted fs.read alone.

Notes / Limitations

• value is an untyped String. By convention store JSON, but the library does not enforce any encoding.
• Versioning is local only; it does not synchronize with remote storage. For distributed conflict resolution use std-sync.
• All four effect kinds (storage_read, storage_write, storage_delete, storage_list) are replay-safe: the runtime records the result in the EventLog and replays it deterministically.

Edit this page on GitHub

std-sync

Offline queue and conflict resolution helpers

Package: std.sync Version: 0.1.0 Capabilities required: net.fetch

Overview

std-sync tracks local-vs-remote divergence and manages an offline edit queue inside framework apps. All conflict-resolution logic is pure; only sync_effect produces a network Effect. Use it to build apps that continue working offline and flush pending changes when connectivity is restored.

Installation

Add to your package.ax.json dependencies:

"std.sync": "0.1.0"

Your policy must grant net.fetch for sync_effect calls to succeed.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

SyncState

type SyncState {
    online: Int,
    pending_count: Int,
    synced_count: Int,
    status: String,
    local_version: Int,
    remote_version: Int,
    conflicts: Int,
    resolved: Int
}

• online — 1 when connected, 0 when offline
• pending_count — number of local edits not yet synced
• synced_count — cumulative count of successfully synced operations
• status — one of "idle", "queued", "syncing", "synced", "offline", "conflict", "resolving"
• local_version / remote_version — monotonic counters; divergence indicates pending changes
• conflicts / resolved — total conflicts detected vs resolved

Functions

Initialization

sync_init() -> SyncState

Returns a fresh sync state: online, no pending edits, version 0.

State transitions

sync_queue_edit(state: SyncState) -> SyncState

Records one new local edit. Increments pending_count and local_version. Sets status to "syncing" if online, "queued" if offline.

sync_mark_synced(state: SyncState) -> SyncState

Acknowledges one successfully synced edit. Decrements pending_count and advances remote_version to match local_version. Status becomes "synced" when the queue is drained.

sync_go_offline(state: SyncState) -> SyncState

Marks the state as offline and sets status to "offline".

sync_go_online(state: SyncState) -> SyncState

Marks the state as online. Status becomes "syncing" if there are pending edits, "synced" otherwise.

sync_detect_conflict(state: SyncState) -> SyncState

Increments the conflict counter and sets status to "conflict". Call when the server rejects an edit due to a version mismatch.

sync_resolve_conflict(state: SyncState, strategy: String) -> SyncState

Increments resolved, bumps local_version, and sets status to "resolving". strategy is passed for audit purposes; conflict resolution logic is app-specific.

Predicates

sync_needs_push(state: SyncState) -> Int

Returns 1 if there are pending edits and the device is online — the signal to fire a sync effect.

sync_is_idle(state: SyncState) -> Int

Returns 1 if status is "idle" or "synced".

sync_has_conflicts(state: SyncState) -> Int

Returns 1 if any unresolved conflicts remain.

Effects

sync_effect(endpoint: String, callback_tag: String) -> Effect

Produces an HTTP request effect targeting endpoint. Return this from update when sync_needs_push is true.

Example

fn main() -> Int {
  let s0: SyncState = sync_init()
  let s1: SyncState = sync_queue_edit(s0)
  let s2: SyncState = sync_go_offline(s1)
  let s3: SyncState = sync_queue_edit(s2)
  let s4: SyncState = sync_go_online(s3)
  s4.pending_count
}

Capabilities

Requires net.fetch for sync_effect. All state-transition functions are pure and require no capability.

Notes / Limitations

• sync_resolve_conflict records a resolution but does not merge data. The calling app is responsible for choosing and applying the correct value before calling this function.
• sync_needs_push checks connectivity and pending count only; rate-limiting and retry backoff are not built in. Combine with std-http’s RetryConfig for production use.

Edit this page on GitHub

std-testing

High-level test helpers for framework apps

Package: std.testing Version: 0.1.0 Capabilities required: none

Overview

std-testing provides assertion functions and aggregation helpers for writing deterministic unit tests directly in .ax. Use it inside fn main() test programs or alongside the boruna framework test command to verify app behavior. Because everything is pure, test programs are fully deterministic and replay-safe.

Installation

Add to your package.ax.json dependencies:

"std.testing": "0.1.0"

API Reference

Types

TestResult

type TestResult { passed: Int, label: String, detail: String }

• passed — 1 if the assertion succeeded, 0 if it failed
• label — the name of this test case
• detail — "ok" on success, or a short failure reason

TestSummary

type TestSummary { total: Int, passed: Int, failed: Int }

Aggregate result for a group of tests.

Functions

Assertions

assert_eq_int(actual: Int, expected: Int, label: String) -> TestResult

Passes if actual == expected.

Example

fn main() -> Int {
  let r: TestResult = assert_eq_int(2 + 2, 4, "addition")
  r.passed
}

assert_eq_string(actual: String, expected: String, label: String) -> TestResult

Passes if actual == expected.

assert_true(value: Int, label: String) -> TestResult