@arxo/law-engine

The Arxo Law engine as WebAssembly: compile .law packages, check them, and evaluate cases with byte-identical results in Node.js, browsers and workers. The modules have zero imports — no WASI, no clock, no environment — so the same request gives the same bytes anywhere.

Which package do you need?

Quickstart

npm install @arxo/law-engine

Check a package with a typo in it:

import { loadEngine } from '@arxo/law-engine/node';

const engine = await loadEngine();
const source = `language "law.core" version "0.2";
package demo.age version "0.1.0";
namespace "urn:example:demo-age";

pub entity Person;
pub relation age(p: Person, years: Integer) kind empirical;
pub relation adult(p: Person) kind institutional;

rule Adult(p: Person, y: Integer) strict {
  when aeg(p, y);
  when y >= 18;
  then adult(p);
}
`;
const { answer } = engine.call({ op: 'check', path: 'demo.law', files: { 'demo.law': source } });

answer.ok;                    // false
answer.diagnostics[0].code;   // 'LDC-E2102'
answer.diagnostics[0].message // 'predicate "aeg" is not declared as a relation in this file'
answer.diagnostics[0].primarySpan.start; // { line: 10, character: 8, offset: 284 }

Fix aeg → age and compile the package to its canonical intermediate representation:

const lowered = engine.call({ op: 'lower', path: 'demo.law', files: { 'demo.law': fixed } }).answer;
const ir = JSON.parse(lowered.bytes);
ir.semanticVersion;            // '0.2.5'
ir.artifactHash;               // 'sha256:e2c51767…'
engine.semanticHash(ir);       // the freshness fingerprint

Measured on a developer laptop (Node 20, 2026-10-02): loadEngine() 75 ms, check of this package 44 ms.

Two modules

Both main modules answer an evaluation request with byte-identical documents. The core module has no compiler at all: the full wrapper refuses a core module at instantiation instead of failing on the first call.

Evaluate

import { loadCoreEngine, REQUEST_SCHEMA } from '@arxo/law-engine/core/node';

const core = await loadCoreEngine();
const program = core.load(ir);            // load once
const { document } = program.evaluate({   // evaluate many cases
  schemaVersion: REQUEST_SCHEMA,          // 'law.core.evaluation-request/0.2'
  semanticVersion: ir.semanticVersion,
  case: caseDocument,
  query,
});
program.dispose();

document is the evaluation document: results, proof graph, issues and hashes. The request envelope is closed — schemaVersion and semanticVersion are required, execution options live in case.options. Building caseDocument by hand is rarely needed: @arxo/law assembles it from plain facts and checks them against the package first.

Run it anywhere

import { LawEngine } from '@arxo/law-engine';

const wasmUrl = new URL('@arxo/law-engine/law_wasm.wasm', import.meta.url);
const engine = await LawEngine.instantiate(await fetch(wasmUrl));

import { createWorkerEngine } from '@arxo/law-engine/worker';

const worker = new Worker(new URL('@arxo/law-engine/worker-entry', import.meta.url), { type: 'module' });
const engine = createWorkerEngine(worker, new URL('@arxo/law-engine/law_wasm.wasm', import.meta.url).href);
await engine.init();
const result = await engine.call({ op: 'features' });
worker.terminate();

import { Worker } from 'node:worker_threads';
import { createRequire } from 'node:module';
import { createWorkerEngine } from '@arxo/law-engine/worker';

const resolve = createRequire(import.meta.url).resolve;
const worker = new Worker(resolve('@arxo/law-engine/worker-node-entry'));
const engine = createWorkerEngine(worker, resolve('@arxo/law-engine/law_wasm.wasm'));
await engine.init();
worker.terminate();

const { answer } = engine.call({
  op: 'ask', path: 'pkg', files,
  args: {
    case: 'Main',
    evaluate: 'evaluate truth(demo.rules::eligible("Ada"));',
    queryId: 'urn:law:demo:case#case/Main/query/eligible',
  },
});

API

Compiler palette — full module

engine.call(request) returns { answer, bytes }; bytes are the canonical form of answer.

Engine

Failures

Wherever the engine itself answers, a failure is a value: { error: { code, message } } or an envelope with ok: false. The wrapper throws only for misuse and for an explicit host failure, as HostAdapterError with code and message (preserved across workers). Match diagnostics on their stable code (LDC-E…), not on the message text. The loader refuses a module built for another ABI version.

Types

Every document and diagnostic is typed from the normative JSON schemas in @arxo/law-types, the package's only dependency, and re-exported here:

import type { EvaluationDocument, Diagnostic } from '@arxo/law-engine';

Links

arxo.io · @arxo/law · Apache-2.0