Lispex Evaluator and LIT

Topaz provides two Lispex surfaces. topaz lispex embed run evaluates a single rule and writes its result without package configuration or a build step. LIT (Lispex-in-Topaz) is a Topaz-written interpreter source exercised through direct execution, generated Rust, generated Python, and Web routes as the Lispex test and integration surface.

What Lispex is

Lispex is a purpose-built Lisp for decision rules, designed 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 the Topaz integration boundary.

Run one request with declared resource limits

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 uses its fixed component, profile, runtime, and route behavior. It performs no component discovery, download, callback, or fallback. The report records Topaz execution and admission; the application artifact API produces portable Lispex-format cores.

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 record identifies the program, routes, inputs, and observed results. Unsupported operations return explicit errors. All four routes share one source lineage and expose checking, lowering, runtime, and host regressions across those routes.

Product boundary

The installed evaluator processes the documented component, profile, file inputs, resource limits, and output contract through topaz lispex embed. Topaz output-target selection remains separate: --target lispex and --target lit reject before artifact output. LIT resides in the repository test and integration system outside the installed package.

Use Lispex inside a Topaz application

A package binds named Lispex rules to the complete-current-profile evaluator, source, resource 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 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 complete-current-profile application runs in the interpreter and generated native products on all five native release targets. Its installed package covers npm installation, source and compiler removal, relocation, multi-input execution, resource-limit refusal, deadline recovery, artifact verification, and fresh replay. Python, Web, HTTP service, no-capability, and empty-component MCP routes reject before artifact output or execution. The Topaz 5.18 compatibility route remains available through the embedded-core compatibility profile with its own component, profile, contract, and prepared-artifact identity.