Topazdocs
Interop

Lispex Evaluator and LIT

Use the installed bounded Lispex evaluator and distinguish it from the Topaz-written LIT integration evidence.

This page describes Topaz v5.17. Before treating it as current, compare /version.json with version 5.17.

Topaz exposes two deliberately separate Lispex boundaries. The installed bounded evaluator runs one closed request through exact component bytes. LIT is a Topaz-written interpreter used as same-lineage dogfood and integration evidence. Neither is a Topaz backend or a claim that Topaz and Lispex are equivalent languages.

Choose the right path

  • To run one installed bounded evaluator request, 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 a regular Lispex rule file, a canonical lispex.embed-value/v1 input, and a closed limits file. Then choose a new output directory:

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

The limits document has this exact shape. Lower values are allowed, 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 refused request or engine failure produces no 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. 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 provider receipt.

What the LIT evidence means

LIT is written in Topaz, and one 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 means the named program behaved as expected on the named routes and within the capabilities selected by that check. Unsupported capabilities fail explicitly. Because all four routes come from one source lineage, their agreement is useful regression evidence, not evidence from four independent implementations and not proof that the two languages are equivalent.

Product boundary

The bounded evaluator is included in the installed Topaz binary, but it admits only its documented component, profile, file inputs, limits, and output contract. It is not --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 there is no --target lit path. Its checks do not turn every Lispex program into a supported Topaz application.