@governed-ai/democraft-runtime

DEMOCRAFT is a demo-orchestration runtime — a deterministic, signal-driven finite-state-machine (FSM) engine for building guided, scripted product walkthroughs and validating that they ran exactly as authored. It executes a storyboard (features → flows → steps), advances strictly on the signals it is told to expect, and produces a strict pass/fail evaluation of the run.

It carries no application domain logic, no database driver, and no built-in content. A host application supplies persistence and storyboard content through documented extension seams.

• Deterministic — step advancement is governed solely by the signals a step declares as required. Given the same signals in the same order, a run always produces the same execution state and the same evaluation. No LLM, no clocks, no randomness in the decision path.
• Content-agnostic — the runtime ships zero storyboards. The host registers its own content via registerStoryboard(). DEMOCRAFT knows how to run a storyboard, never what it contains.
• Persistence-agnostic — the runtime talks to a DemocraftPersistence port; the host injects a concrete adapter (e.g. a Drizzle/Postgres implementation) via configureDemocraftPersistence().
• Strictly evaluated — every completed session can be evaluated into a pass/fail report with per-criterion evidence, so a demo is verifiable, not just runnable.

What problem does it solve?

Scripted product demos are fragile: steps get skipped, timing drifts, and there is usually no machine-checkable proof that the demo actually did what it was supposed to. DEMOCRAFT turns a demo into a verifiable state machine — each step declares the exact signals required to advance, and the evaluation engine emits a deterministic verdict (pass / fail) with evidence. This makes a demo a regression-testable asset, not a manual ritual.

How does it differ from PADP Runtime?

| | @governed-ai/padp-runtime | @governed-ai/democraft-runtime | | --- | --- | --- | | Concern | Governed AI decisioning (intelligence pipeline, governance gate, artifacts) | Demo orchestration (FSM, signals, evaluation) | | Decides | Whether/how a skill runs under policy | Whether a demo step may advance | | Output | Governed intelligence artifacts | Execution state + pass/fail evaluation | | Relationship | Foundational runtime | Independent — no dependency on PADP Runtime |

DEMOCRAFT is a fully independent runtime. It does not depend on @governed-ai/padp-runtime (its only external dependencies are zod and pino), and it does not drive, wrap, or govern PADP intelligence requests.

How does HEART use it?

HEART (a host application) embeds DEMOCRAFT to script and verify product walkthroughs:

1. Implements a DemocraftPersistence adapter and installs it with configureDemocraftPersistence().
2. Authors storyboard content (features, flows, steps) and registers it with registerStoryboard().
3. Drives the engines (storyboardLoader, sessionManager, executionEngine) from its own routes/UI to launch sessions and feed signals.
4. Calls evaluationEngine.evaluateSession() to obtain a deterministic verdict.

The reference in-repo host (@workspace/api-server) does exactly this; see docs/QUICK_START.md.

Install

npm install @governed-ai/democraft-runtime

Requires Node.js >=22. See docs/INSTALLATION.md.

Quick start

import {
  configureDemocraftPersistence,
  registerStoryboard,
  storyboardLoader,
  sessionManager,
  executionEngine,
  evaluationEngine,
} from "@governed-ai/democraft-runtime";

configureDemocraftPersistence(myAdapter);   // 1. host persistence
registerStoryboard(myCatalogEntry);          // 2. host content

await storyboardLoader.loadStoryboard({ storyboardId: "demo", flowIds, featureIds });
const session = await sessionManager.createSession({ storyboardId: "demo", requestedBy: "host" });
await executionEngine.receiveSignal(session.sessionId, "ui-action");
const evaluation = await evaluationEngine.evaluateSession(session);

Full runnable walkthrough: docs/QUICK_START.md.

Public API surface

The package exposes a single curated entry point — @governed-ai/democraft-runtime. Internal modules are not importable from the published package.

| Export | Kind | Purpose | | --- | --- | --- | | configureDemocraftPersistence, getDemocraftPersistence | function | Persistence injection seam | | DemocraftPersistence + repository/DTO types | type | Contract the host adapter implements | | registerStoryboard, getCatalogEntry, listRegisteredStoryboards, clearStoryboardCatalog | function | Storyboard content registry | | StoryboardCatalogEntry | type | Shape of registered content | | storyboardLoader, sessionManager, executionEngine, evaluationEngine, featureRegistry, flowRegistry | object | Engine singletons | | Domain types (DemoFeature, DemoFlow, DemoStep, DemoExecutionState, DemoEvaluation, SignalType, …) | type | The DEMOCRAFT domain model | | Contract schemas (*Schema, *Contract) | object/type | Zod/TS API contracts for host routes |

Full enumeration: repository docs/PHASE_7H_PUBLIC_API_INVENTORY.md.

Documentation

• docs/INSTALLATION.md — install, requirements, host wiring
• docs/QUICK_START.md — minimal end-to-end embedding
• docs/STORYBOARD_AUTHORING_GUIDE.md — author features, flows, steps
• docs/SIGNAL_GUIDE.md — the signal model & advancement semantics
• docs/EVALUATION_GUIDE.md — evaluation criteria & verdicts
• docs/DIAGNOSTICS_GUIDE.md — traces, logging, troubleshooting
• docs/NARRATION_POSITIONING.md — narration ownership & guarantees

License

UNLICENSED — distribution is controlled by the platform owner.