Runtime architecture

OmegaRuntime is the embeddable runtime entry point. One instance owns one evaluator, one driver registry, one default profile, and one snapshot/receipt repo.

The config

// projects/omega-lisp/src/runtime.ts:37-61
type OmegaConfig = {
  adapter?: OracleAdapter;             // explicit oracle adapter (optional — auto-detected from env)
  maxOracleDepth?: number;             // default 4 — how many nested oracle calls
  defaultCaps?: CapSet;                // capability set for new contexts
  defaultBudgets?: BudgetLimits;       // remaining oracle turns / eval steps / tool calls
  profile?: Profile;                   // truth regime; default DEFAULT_PROFILE
  maxSteps?: number;                   // default 500_000
  registry?: DriverRegistry;           // driver registry for named-driver routing
  defaultDriver?: string;              // default name to use when payload has no :driver
};

Construction

import { OmegaRuntime, populateRegistryFromEnv } from 'omega-lisp';
import { DriverRegistry } from '@open-matrix/inference';

const registry = new DriverRegistry();
await populateRegistryFromEnv(registry);   // pulls in available drivers from env

const omega = new OmegaRuntime({ registry, defaultDriver: 'anthropic' });

const result = await omega.eval('(+ 1 2)');
// { ok: true, value: { tag: 'Num', n: 3 } }

The constructor:

Builds a fresh Ctx rooted from the chosen profile (ctxRootFromProfile).
Installs the standard primitive set (installPrims).
Wires the RuntimeImpl effect backend with the driver registry.
Initializes a snapshot repo + an in-memory receipt store.

The four entry-point methods

Method	Returns	Purpose
`eval(text)`	`EvalResult`	parse + evaluate one source string
`evalAst(expr)`	`EvalResult`	evaluate a pre-parsed `Expr`
`infer(prompt, opts)`	`InferResult`	one-shot oracle call returning a `Meaning`
`dispose()`	`void`	release driver-side resources

EvalResult is { ok, value? | error? }; InferResult is { ok, meaning?, value?, confidence?, error? }.

How `infer` differs from `eval`

eval("(effect infer.op …)") parses the source, runs the CESK loop, dispatches the effect, and returns the result.

infer(prompt, opts) skips the parsing/CESK round-trip and goes straight through the oracle adapter. It returns a Meaning (semantic content + provenance), which eval does too if you wrap it.

Use infer for "I just want one prompt out of this runtime"; use eval when the oracle call is part of a larger Lisp program.

`populateRegistryFromEnv`

runtime.ts:102-… is a helper that auto-registers drivers based on env vars:

ANTHROPIC_API_KEY   → @open-matrix/driver-anthropic   (via dynamic import)
OPENAI_API_KEY      → @open-matrix/driver-openai
OLLAMA_BASE_URL     → @open-matrix/driver-ollama

If a driver package isn't installed, the helper silently skips it. This is what powers the "auto-detect from env" path the REPL uses.

Snapshot and receipt repos

Every runtime has:

SnapshotRepo (in-memory by default) — for :save/:restore.
InMemoryReceiptStore — for tracking oracle receipts.

For persistent storage, swap in FileProvenanceStore (src/core/provenance/store/file.ts).

Runtime architecture ​

The config ​

Construction ​

The four entry-point methods ​

How infer differs from eval ​

populateRegistryFromEnv ​

Snapshot and receipt repos ​

See also ​