Topazdocs
Interop

Lispex Evaluator and LIT

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

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 Lispex-format portable receipt core.

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.

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 gets new 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 enough. Use evaluateWithEvidence when an eligible deterministic settlement also needs 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, Topaz component admission, or permission to perform an external action. Local preflight refusal, cancellation, queue refusal, operating-system resource failure, safety preemption, and engine faults create no portable core.

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

For the complete manifest, rule, limit, lock, build, run, evidence, and replay workflow, use Bounded Lispex Decision Application. The guide does not turn LIT into a backend or widen the restricted profile.