Lispex Evaluator

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. Topaz 5.21 includes Lispex 1.21. A rule cannot access files, the network, or the system clock during evaluation.

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.

LIL and LIT retirement

LIL and LIT completed their role in internal cross-validation and were retired to reduce ongoing maintenance costs. They no longer receive feature updates, new releases, or installation and execution support. New cross-validation runs and LIT candidate acceptance are no longer release requirements.

LIT means Lispex-in-Topaz. Its Topaz-written interpreter helped compare direct execution, generated Rust, and Web results. Research sources, recorded inputs and results, and earlier versions remain available as historical material.

Use the evaluator command or std.lispex above for current applications. The evaluator, its resource limits, cancellation, value codec, and application records continue to serve those applications. --target lispex and --target lit are rejected before output files are written.

The earlier retirement of the Topaz VM and AOT companion products was a separate change. The Lispex evaluator continues to use its supported execution engines. Topaz continues to compile itself with its compiler written in Topaz.

Related documentation

• Interop Boundaries
• Rust Backend