Embedding the portable Arboricx reader

The reader in lib/arboricx/arboricx.tri is itself a tricu program. A host can load a compiled reader entrypoint, supply application bundle bytes and arguments, and decode the returned value. This keeps bundle parsing and result validation in tricu while the host supplies Tree Calculus execution.

This guide describes the embedding boundary. For native development and validation with the Haskell host, follow Build and run.

Two programs

The reader program exposes entrypoints such as runArboricxToString. Load it from an authenticated compiled artifact, either using a host bundle reader or a predecoded shared tree representation.

The application program is an Arboricx bundle supplied as a canonical byte list. Arguments are a canonical list of tree values. A string-output invocation has this application structure:

((runArboricxToString bundleBytes) arguments)

Application is an evaluator operation, distinct from the data constructor Fork function argument. Preserve that distinction in the host representation. The Haskell reference is src/Runtime.hs; the browser implementation is under ext/demo-site/src/.

Select an entrypoint

Purpose	Default export	Named export
Decode an executable	readArboricxExecutable bytes	readArboricxExecutableByName name bytes
Apply one argument	runArboricx bytes arg	runArboricxByName name bytes arg
Apply an argument list	runArboricxArgs bytes args	runArboricxArgsByName name bytes args
Check and wrap a string result	runArboricxToString bytes args	runArboricxByNameToString name bytes args

Typed runners also provide Tree, Number, Bool, List, and Bytes variants. Names are UTF-8 byte lists. Default selection chooses main, or the sole export when there is exactly one. Multiple exports without main require a named call.

Decode the result

All runners return the ordinary outer Result protocol:

ok value rest = pair true  (pair value rest)
err code rest = pair false (pair code rest)

Raw runners return the application's tree. Typed runners return a tagged value, for example ok (hostString characters) rest. Unwrap the Result, then its pair tag payload envelope, then decode the payload for that tag. Host ABI specifies canonical encodings and codec failures.

The reader validates the bundle, reconstructs the selected tree from backward node indices, and applies arguments in order. Typed result validation happens after application. Preserve shared branches while loading; walking the expanded logical tree can require far more work than the indexed input size suggests.

Verification

Use the bundle format and its reader profiles when choosing an ingestion boundary. Authenticate selected artifact bytes and set input, execution, and result-observation budgets independently. A valid bundle can contain a program that does not terminate.

test/Spec.hs covers executable selection, ordered arguments, canonical codecs, and typed success/failure results. The browser has independent parser and runtime controls. See Testing for reference-artifact and candidate checks.