Lispex Evaluator and LIT

Run one Lispex rule from the command line and read its result or resource-limit report. To call rules repeatedly from your application, follow Run Lispex Rules.

Install Topaz before starting. The included evaluator uses Lispex 1.20.0. It cannot access files, the network, or the system clock while evaluating a rule.

Prepare three files

Create a working folder and save rule.lspx there.

(if (< 10 15) "allow" "deny")

Lispex is a Lisp for decision rules, with syntax close to Scheme. This rule compares two constants and returns "allow". It ignores the input. For language details, see Lispex.

In the same folder, create value.lpxvalue with one of the following commands. Use a Bash-compatible shell for the first command or PowerShell for the second.

printf '\000' > value.lpxvalue

PowerShell

[IO.File]::WriteAllBytes((Join-Path (Get-Location) 'value.lpxvalue'), [byte[]]@(0))

The file contains one byte, 00, which encodes the empty value nil in lispex.embed-value/v1. It is a binary file. Typing the characters 00 into a text editor creates a different input.

Save the following complete file as limits.json.

{
  "schema": "topaz.lispex-embed-limits/v1",
  "prepare": {
    "raw_source_bytes": 4096,
    "prepare_work": 1000000,
    "logical_allocation": 1000000,
    "syntax_depth": 64
  },
  "evaluate": {
    "canonical_input_bytes": 4096,
    "eval_work": 10000,
    "logical_allocation": 1000000,
    "semantic_frames": 1000,
    "traversal_depth": 256,
    "output_bytes": 4096,
    "diagnostic_bytes": 4096,
    "transcript_bytes": 4096,
    "transcript_events": 100,
    "result_bytes": 4096
  }
}

Keep all fields. You may lower the values, but adding or omitting a field makes the limits document invalid. eval_work counts evaluator work. Run Lispex Rules explains per-rule limits and application quotas.

Run and read the result

From the folder containing the three files, run this command. The output folder lispex-result must not exist yet.

topaz lispex embed run --source rule.lspx --input value.lpxvalue --limits limits.json --output lispex-result

The command exits with code 0 and no stdout. It creates lispex-result/report.json and lispex-result/result.lpxvalue. Open the report and find its outcome object.

{ "category": "complete", "code": "complete", "operation": "evaluate" }

result.lpxvalue holds the binary result. The report also records the rule, input, limits, evaluator, runtime, and resource usage.

To see a work-limit result, copy limits.json to small-limits.json and change evaluate.eval_work from 10000 to 1. Keep the other fields. Choose a new output folder.

topaz lispex embed run --source rule.lspx --input value.lpxvalue --limits small-limits.json --output lispex-limit

This command also exits with code 0 and no stdout. lispex-limit/report.json contains this outcome.

{ "category": "limit-exhaustion", "code": "eval_work", "operation": "evaluate" }

There is no result.lpxvalue because the rule did not finish. Restore eval_work to 10000 and choose another unused output folder to complete the evaluation. The CLI's exit code tells you that it wrote the evaluation report. Read outcome.category to distinguish completion, a semantic failure, and a resource limit.

Check the installed evaluator

topaz lispex embed info --json

The command exits with code 0 and prints JSON. These fields identify the component and value format used by the standalone CLI.

A profile names the supported features and execution rules. The command uses its installed component and profile. It does not discover or download another component, call a host callback, or switch to another evaluator on failure.

Call rules from an application

Use std.lispex and generated rule functions in std.lispex.rules for package integration. Run Lispex Rules provides every file, the normal output, and a work-limit output.

The application profile is lispex/r7rs-rule-current-profile-bounded/1. Each evaluation starts with fresh memory, globals, resource counters, and an execution log. The application also enforces quotas, deadlines, cancellation, and cleanup.

Use evaluate for the result and evaluateWithEvidence for a result with a saved record when available. The guide describes storage, inspection, verification, extraction of the Lispex-format core, and freshReplay.

These records are unsigned and unauthenticated. They carry no issuer, provider approval, signing authority, component approval, or permission for external actions. Local refusal, cancellation, queue refusal, a protective stop, and engine failure produce no portable core.

Applications run through the interpreter or native products on the five native release targets. A built native executable can run after relocation and removal of the project source and compiler. Web, no-capability, and empty-component MCP routes reject execution or output generation. Existing Topaz 5.18 packages retain their separate embedded-core compatibility profile and prepared-rule identifiers. A rejected route never switches to another profile or runtime.

Understand LIT tests

LIT means Lispex-in-Topaz. It is an interpreter written in Topaz and used to test the toolchain. The tests run the same source through direct execution, generated Rust, and Web.

Test records identify the source, routes, inputs, and observed results. They help locate errors in checking, code generation, runtime behavior, and interaction with the calling program. Unsupported operations return explicit errors.

LIT belongs to the repository's test system and is not included in the installed package. --target lispex and --target lit are rejected before output files are written. Use the CLI command or the application API above to evaluate rules.

Related documentation

• Interop Boundaries
• Rust Backend