Sebastián Diéguez (SebaSOFT)

Posted on Sep 29 Originally published at sebasoft.github.io

Deterministic business rules for AI agents: how neuron-js validates, executes and explains JSON rule scripts

#ai #typescript #rulesengine #webdev

AI agents are getting good at writing business logic. That's exactly the problem.

An agent generates a pricing rule that looks perfect: reads well, matches the request, even passes a quick test. But nobody can verify it. Can you replay yesterday's decision? Can you prove to an auditor why customer X got discount Y?
Can you be sure the rule that ran is the rule that was reviewed?

At SebaSOFT we kept hitting this failure mode while building AI-driven workflow automation, so we built neuron-js — an
MIT-licensed TypeScript library where every rule set is pure JSON, validated before execution, and explained after it. This post walks through why those three properties matter for AI workflows and how the pieces fit together.

Rules as data, not code

In neuron-js, a ruleset is an ExecutionScript: a JSON document containing rules, and each rule contains conditions and actions. It serializes, diffs cleanly in pull requests, versions in git, and moves between environments without transpilation:

{
  "id": "volume-discount",
  "rules": [
    {
      "id": "discount-rule",
      "type": "simple_rule",
      "options": {},
      "conditions": [
        {
          "id": "quantity-check",
          "type": "compare_two_numbers",
          "options": {},
          "params": [
            { "id": "p1", "name": "op1", "type": "simple_number", "value": "${quantity}", "options": {} },
            { "id": "p2", "name": "comp", "type": "comparator", "value": ">", "options": {} },
            { "id": "p3", "name": "op2", "type": "simple_number", "value": "100", "options": {} }
          ]
        }
      ],
      "actions": [
        {
          "id": "apply-discount",
          "type": "add_two_numbers",
          "options": {},
          "params": [
            { "id": "a1", "name": "op1", "type": "simple_number", "value": "${price}", "options": {} },
            { "id": "a2", "name": "op2", "type": "simple_number", "value": "-10", "options": {} }
          ]
        }
      ]
    }
  ]
}

Two components make this run:

Neuron — the registry. It holds every registered condition, action, parameter and rule type. The built-in registry ships with the standard comparison and arithmetic plugins; you register your own types for domain logic.
Synapse — the execution engine. Give it a Neuron instance, an ExecutionScript and an ExecutionContext (the shared state object), and it evaluates conditions and fires actions in order.

Because logic lives in data, an AI agent can author rules — and because the schema is strict, whatever the agent writes gets machine-validated before it can touch anything real.

Fail-closed by design

Every execution path validates first:

import { Neuron, Synapse, validateScript } from "@sebasoft/neuron-js";

const validation = validateScript(scriptJson);
if (!validation.ok) {
  // exact errors, nothing executed — ever
  console.error(validation.errors);
} else {
  const result = new Synapse(new Neuron()).execute(scriptJson, context);
}

An invalid script never executes. It returns the exact validation errors
instead of a half-evaluated result. This is the property that makes AI-generated rules auditable: the schema is the contract, and the contract is enforced by the runtime, not by convention.

The explanation trace

Every run can produce an ExecutionExplanation: which rules matched, which conditions evaluated true or false, and in what order. For compliance and debugging this changes the conversation from "trust the engine" to "here is the trace of decision #4821."

Combined with determinism — same script, same context, same output, every
time — you get replayability: store script + context, replay any decision
exactly, prove the outcome matches the trace.

An MCP server in the box

The piece that connects all of this to AI agents is the bundled MCP server.
Claude Desktop, Cursor, or any MCP client can register three tools —
validate_script, execute_decision, explain_decision — and operate rule
sets without writing integration code:

{
  "mcpServers": {
    "neuron-js": {
      "command": "node",
      "args": ["/absolute/path/to/neuron-js/examples/mcp-server/run.ts"]
    }
  }
}

The server is read-only and deterministic. Every tool call validates its inputs first (fail-closed again) and returns JSON. An agent can validate a rule it just wrote before proposing it, execute it against test contexts, and explain the result — the full authoring loop.

Honest benchmarks

Our benchmark harness compares neuron-js against json-rules-engine, json-logic-js, node-rules and hand-coded TypeScript across three scenarios (pricing, eligibility, routing) and three input sizes. On Node 24, yarn benchmark reproduces every number:

~5x throughput vs json-rules-engine (medium pricing scenario)
~3x smaller minified bundle
json-logic-js is faster in pure evaluation — but it has no validation step and no explanation trace. If you need those (and for AI-generated rules you do), the comparison isn't speed vs speed.

The fairness gates and full methodology are in the repo. If a number looks
wrong, the harness prints it — file an issue.

Agent-first documentation

Because the primary reader of this documentation is often an agent, the site practices what it preaches: an llms.txt router with a full-text variant, Markdown mirrors of every page served at the same URLs (rel="alternate" type="text/markdown"), MCP tools exposed on the site itself, and a robots.txt that explicitly welcomes AI crawlers and fetchers.

The result is a discovery loop that matches the product: an agent can find
neuron-js through a search, read its documentation in clean Markdown, register its MCP server, validate a rule, execute it, and explain the outcome — end-to-end without a human in the middle. The human shows up at the review step, which is exactly where the schema guarantees your leverage.

Try it

Questions about the benchmark methodology, the MCP integration, or the
validation schema? Happy to go deeper in the comments.

DEV Community