@sutraa/kalpa-runtime

@sutraa/kalpa-runtime runs a canonical Kalpa manifest as a deterministic in-memory command state machine. It owns logical time, ordered events, state snapshots, command rejection diagnostics, reset, and replay. It does not render UI or interpret behavior.effect strings.

npm install @sutraa/kalpa-runtime

Create a runtime

Pass a valid canonical ExperienceManifest, preferably one returned by compileManifest from @sutraa/kalpa-compiler.

import { createKalpaRuntime } from "@sutraa/kalpa-runtime";

const runtime = createKalpaRuntime(manifest);
console.log(runtime.getState());
// { selectedEntityId: null, inspectedEntityId: null, inspectionOpen: false, logicalTime: 0 }

Dispatch commands

Every command includes a declared source: dom, canvas, cli, or agent. dispatch returns an accepted result with an optional committed event, or a rejected result with a diagnostic. Existing state is never mutated in place; getter methods return snapshots.

| Command | Preconditions | Accepted state change | Event | | --- | --- | --- | --- | | select-entity | entity exists and declares selectable | sets selectedEntityId | entity-selected | | inspect-entity | entity exists and declares inspectable | selects entity, opens inspection | inspection-opened | | reset-experience | none | restores initial state | experience-reset |

const selected = runtime.dispatch({
  type: "select-entity",
  entityId: "pump",
  source: "cli",
});

if (!selected.accepted) {
  console.error(selected.diagnostic);
} else {
  console.log(selected.event?.sequence); // 1
}

runtime.dispatch({ type: "inspect-entity", entityId: "pump", source: "cli" });
console.log(runtime.getState().inspectedEntityId); // "pump"
console.log(runtime.getEvents());                  // ordered events, logical times 1 then 2

Rejection diagnostics

The runtime rejects invalid interaction commands deterministically. The diagnostic codes are ENTITY_NOT_FOUND, CAPABILITY_UNAVAILABLE, and COMMAND_UNSUPPORTED. Rejections are returned from dispatch; they are also retained by getDiagnostics().

const result = runtime.dispatch({
  type: "inspect-entity",
  entityId: "unknown-pump",
  source: "agent",
});

if (!result.accepted) {
  console.log(result.diagnostic?.code); // "ENTITY_NOT_FOUND"
}

Replay a command list

replay creates a fresh runtime from the same manifest and applies commands in order. It does not alter the current runtime. This is useful when a host or test needs to check that the same command sequence produces the same state and events.

const replay = runtime.replay([
  { type: "select-entity", entityId: "pump", source: "cli" },
  { type: "inspect-entity", entityId: "pump", source: "cli" },
]);

console.log(replay.state.inspectionOpen); // true
console.log(replay.events.length);        // 2

What this package does not do

The runtime does not load files, validate every manifest reference, render a representation, persist state, schedule work, or run arbitrary behavior strings. Use @sutraa/kalpa-compiler for validation and file/artifact operations; provide your own host or renderer around the runtime.

License

MIT. Requires Node.js 18 or later.