Runtime Adapter

The PlaygroundRuntimeAdapter interface defines the contract between the UI and any execution backend.

interface PlaygroundRuntimeAdapter {
  validate(source: PlaygroundSource): Promise<ValidationResult>
  compile(source: PlaygroundSource): Promise<CompileResult>
  execute(request: ExecuteRequest, callbacks?: ExecutionCallbacks): Promise<ExecutionResult>
  replay(request: ReplayRequest, callbacks?: ExecutionCallbacks): Promise<ReplayResult>
  runQuery(request: QueryRequest): Promise<QueryResult>
}

Current implementation

Local mode (default)

BrowserPlaygroundAdapter in @causet/playground-runtime provides:

StageImplementation
ParseYAML parser with multi-file @file splitting
ValidateSchema checks for states, actions, events, projections, queries
CompileProduces internal IR (CompiledIR)
ExecuteRules engine with preflight, core, and side-effect phases
ProjectionsIn-memory table materialization with upsert/insert/delete
QueriesSQL-like filtering against projection tables
ReplayRe-processes event ledger into projections

Live Causet mode

Toggle Live Causet in the sidebar to execute against a real Causet deployment. This uses:

PackageRole
@causet/causet-sdkTypeScript port of the jamlet causet-sdk-python HTTP client
@causet/playground-sdk-adapterImplements PlaygroundRuntimeAdapter — local compile/validate, remote execute
/api/causet/proxyNext.js API route that forwards requests to Causet (avoids browser CORS)

In Live mode, Run still compiles DSL locally, then sends each command as an intent via POST .../intents/execute. Queries run against the remote fork; projections are skipped (they materialize asynchronously on the server).

Connection settings (sidebar):

  • API URL — e.g. https://api.causet.cloud
  • Platform slug, app slug, fork (default main)
  • API key or bearer token

You can also set server-side defaults with environment variables on the docs site:

CAUSET_API_URL=
CAUSET_API_KEY=
CAUSET_BEARER_TOKEN=

Replay is not available in Live mode — switch back to Local for event replay in the browser.

Rules engine

Intents execute in three phases matching production Causet:

  1. Preflight — validation rules that can reject intents
  2. Core — state mutations (set, add)
  3. Side effects — event emission via emit

Expressions in when clauses evaluate against intent and state contexts.

Replacing with production runtime

The tutorials already ship a Live adapter backed by @causet/causet-sdk. For deeper integration (WASM compiler, WebSocket streaming, server-only credentials):

  1. Extend CausetSdkAdapter or implement a new PlaygroundRuntimeAdapter
  2. Call SaaS product-spec/compile for compilation instead of the browser parser
  3. Stream entity updates via the SDK WebSocket client
  4. Map production errors to Diagnostic objects

The UI, examples, persistence, and share URLs remain unchanged.

Callbacks for streaming

Pass ExecutionCallbacks to receive live updates:

  • onEvent — each ledger event as it’s appended
  • onProjection — projection materialization results
  • onQuery — query execution results
  • onStateChange — aggregate version snapshots
  • onLog — structured runtime logs
  • onTimelineUpdate — execution graph nodes
  • onDiagnostic — errors and warnings
What is Causet?