Lispex Evaluator and LIT

Topaz integrates with Lispex in two distinct contexts. The first is a command that evaluates a single Lispex rule and writes the result to a directory, requiring no package or build step. The second is LIT (Lispex-in-Topaz), a Lispex interpreter written in Topaz that serves as test evidence rather than a shippable artifact. Neither component functions as a Topaz backend, nor do they make Topaz and Lispex equivalent languages.

What Lispex is

Lispex is a small Lisp for decision rules, deliberately close to Scheme. One input gives one deterministic answer, and the same rule with the same input always returns the same result.

A request arrives as a list of named fields, and every answer, refusals included, comes back as a list. It is a language separate from Topaz, with its own documentation and its own version scheme. The Lispex site has the detail.

Choose the right path

To embed Lispex rules inside an application, use Run Lispex Rules.
To evaluate a standalone rule without a package, use topaz lispex embed run.
To ship a Topaz application, choose one of the supported Topaz output targets.
To understand LIT, read it as evidence that a substantial Lispex program exercises several parts of the Topaz toolchain together.
To use Lispex as a product, follow the Lispex product documentation. This page describes only the boundary observed from Topaz.

Run one bounded request

Prepare three files. These include a standard Lispex rule file, an input in the canonical lispex.embed-value/v1 encoding, and a limits file that sets every operational ceiling. Then choose an output directory that does not exist yet:

BASH

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

The limits document follows this exact structure. Lower values are permitted, but fields cannot be omitted or added.

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": 1000000,
    "logical_allocation": 1000000,
    "semantic_frames": 1000,
    "traversal_depth": 256,
    "output_bytes": 1000000,
    "diagnostic_bytes": 1000000,
    "transcript_bytes": 1000000,
    "transcript_events": 100,
    "result_bytes": 1000000
  }
}

On success, lispex-result contains result.lpxvalue and report.json. Deterministic semantic failure or limit exhaustion produces only the report. A rejected request or engine failure produces no output directory. Inspect the fixed component and no-fallback policy with:

BASH

topaz lispex embed info --json

The command accepts no evaluator, profile, runtime, or route selector flags. It does not discover or download a component, call back into Topaz, or fall back to LIT. Its report records the Topaz product execution and admission. It is not a portable receipt core in Lispex format.

What the LIT evidence means

LIT is written in Topaz, and a single canonical source lineage is exercised through direct execution, generated Rust, generated Python, and Web routes. This demanding program can expose defects in checking, lowering, runtime behavior, and host boundaries.

A passing LIT check indicates that the named program behaved as expected on the specified routes and within the capabilities selected for that check. Unsupported capabilities fail explicitly. Because all four routes derive from one source lineage, their agreement provides useful regression evidence, rather than evidence from four independent implementations or proof of language equivalence.

Product boundary

The evaluator is included in the installed Topaz binary, but it admits only its documented component, profile, file inputs, limits, and output contract. It does not provide --target lispex, a general Lispex toolchain, or whole-language equivalence.

LIT is not included in a Topaz installation. It is not an output target, and no --target lit path exists. Its checks do not convert every Lispex program into a supported Topaz application.

Use Lispex inside a Topaz application

A package can bind named Lispex rules to the exact restricted profile, source, limits, and embedded component. A locked build prepares each rule once and generates std.lispex plus std.lispex.rules. Topaz code receives opaque rule and value types rather than raw Wasm handles. Every evaluation still receives fresh guest memory, globals, meter, and transcript state, while application-wide quotas, cancellation, and cleanup surround the per-call limits.

Use evaluate when the typed settlement is sufficient. Use evaluateWithEvidence when an eligible deterministic settlement also requires a consumer artifact. consumerArtifactBytes preserves it for storage, consumerArtifactFromBytes performs checked intake, and inspectConsumerArtifact or verifyConsumerArtifact reports its stable identity. portableCoreBytes extracts the exact Lispex-format core when one is present. freshReplay re-evaluates the admitted rule and input with the artifact's limits in a fresh guest instance and accepts only an identical artifact.

The core and outer artifact are consumer-produced and unauthenticated. They carry no issuer, provider approval, signing authority, component admission, or permission to perform an external action. Local preflight refusal, cancellation, queue refusal, safety preemption, and engine faults create no portable core.

The application API is admitted by the interpreter and the current generated native route. On the local native route, a maintained two-module package has passed standard npm installation, source and compiler removal, relocation, multi-input execution, limit refusal, deadline recovery, evidence verification, and fresh replay. Python, Web, HTTP service, no-capability, and empty-component MCP routes reject it before output. The Roadmap tracks qualification of every supported native target for one exact release candidate as the next bounded-product gate. Full-profile support remains a separate component, profile, contract, target verification, and admission. It never expands the restricted evaluator in place.