@proophboard/exploration-runtime 0.0.0-stage → 0.1.1

package/dist/types/exploration.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Exploration Mode runtime types (copied from eventflow-designer
+ * src/types/exploration.ts — pure, no imports). Keep in sync; the parity test
+ * guards the runtime behaviour that depends on these shapes.
+ */
+/**
+ * The runtime state tree (R7).
+ *
+ *   state.$events                 — ordered log, index from 0
+ *   state.<Context>.<Element>     — projections, keyed via toClassName()
+ */
+export interface RuntimeState {
+    $events: RuntimeEvent[];
+    [context: string]: unknown;
+}
+/** One entry in the ordered event log (R7). */
+export interface RuntimeEvent {
+    name: string;
+    context: string;
+    payload: Record<string, unknown>;
+    index: number;
+    timestamp: string;
+    /** The id of the slice whose step emitted this event (M5 attribution). */
+    sliceId?: string;
+}
+/** A command produced by interact/react/process and fed into command.decide. */
+export interface RuntimeCommand {
+    name: string;
+    context: string;
+    payload: Record<string, unknown>;
+}
+/** One recorded UI interaction (R26). `storage` collected at a UI step. */
+export interface InteractionLogEntry {
+    stepIndex: number;
+    storage: Record<string, unknown>;
+}
+/** ImplicitScenario — the in-memory scenario the fold consumes. */
+export interface ImplicitScenario {
+    initialState: Record<string, Record<string, unknown>>;
+    seededEvents?: Array<Omit<RuntimeEvent, 'index' | 'timestamp'> & Partial<Pick<RuntimeEvent, 'timestamp'>>>;
+    clock?: string;
+    interactions?: InteractionLogEntry[];
+}
+/** The deterministic reducer output (R3–R5). */
+export interface RuntimeResult {
+    events: RuntimeEvent[];
+    state: RuntimeState;
+}
+/** A handler/runtime error surfaced from the fold (R15, R20). */
+export interface RuntimeError {
+    kind: 'threw' | 'rejected' | 'cascade-exceeded' | 'dangling-reference';
+    message: string;
+    stepIndex: number;
+    sliceId?: string;
+    elementId?: string;
+    elementName?: string;
+    cascadeKind?: 'depth' | 'total-events';
+}
+/** A derived Information view produced by a `read(state)` handler (R11a, R21a). */
+export interface RuntimeReadView {
+    elementId: string;
+    key: string;
+    view: unknown;
+}
+/** An automation-dispatched command not yet reached by the playhead. */
+export interface PendingCommand {
+    commandElementId?: string;
+    name: string;
+    context: string;
+    payload: Record<string, unknown>;
+    sourceAutomationId: string;
+    sourceAutomationName: string;
+    triggeredByEventName?: string;
+}
+/** The reducer output extended for authored handlers (4b). */
+export interface RuntimeResultV2 extends RuntimeResult {
+    errors?: RuntimeError[];
+    readViews?: RuntimeReadView[];
+    pendingCommands?: PendingCommand[];
+    clockISO?: string;
+}
+/** An empty implicit scenario — the default when nothing is seeded. */
+export declare const EMPTY_IMPLICIT_SCENARIO: ImplicitScenario;
+/** Scenario — the persisted, chapter-scoped scenario (superset of Implicit). */
+export interface Scenario extends ImplicitScenario {
+    id: string;
+    chapterId: string;
+    name: string;
+    expectations?: ScenarioExpectation[];
+}
+/** ScenarioExpectation — one pinned, asserted outcome (M5). */
+export interface ScenarioExpectation {
+    id: string;
+    sliceId: string;
+    kind: 'events' | 'information' | 'rejection';
+    elementId?: string;
+    match?: 'exact' | 'subset';
+    expected: ExpectedEvents | ExpectedInformation | ExpectedRejection;
+}
+/** Expected emitted events for an `events` expectation. */
+export interface ExpectedEvents {
+    events: Array<{
+        name: string;
+        context: string;
+        payload?: Record<string, unknown>;
+    }>;
+}
+/** Expected Information value for an `information` expectation. */
+export interface ExpectedInformation {
+    value: unknown;
+    view: 'stored' | 'read';
+}
+/** Expected rejection for a `rejection` expectation. */
+export interface ExpectedRejection {
+    message?: string;
+    elementName?: string;
+}
+/** Narrowing type guards for the expected union. */
+export declare function isExpectedEvents(e: ScenarioExpectation['expected']): e is ExpectedEvents;
+export declare function isExpectedInformation(e: ScenarioExpectation['expected']): e is ExpectedInformation;
+/** The verdict for a single expectation after a run. */
+export interface ExpectationResult {
+    expectationId: string;
+    sliceId: string;
+    kind: ScenarioExpectation['kind'];
+    elementId?: string;
+    matched: boolean;
+    failureKind?: 'mismatch' | 'dangling-reference' | 'threw' | 'cascade-exceeded' | 'rejected-missing' | 'unexpected-events';
+    message?: string;
+    actual?: unknown;
+    expected?: unknown;
+}
+/** The machine-readable outcome of running one scenario as a test (M5). */
+export interface ScenarioRunResult {
+    scenarioId: string;
+    scenarioName: string;
+    status: 'pass' | 'broken' | 'neutral';
+    expectationResults: ExpectationResult[];
+    structuralErrors: RuntimeError[];
+}
+/** Adapter: narrow a persisted Scenario down to the runtime-facing Implicit one. */
+export declare function toImplicitScenario(scenario: Scenario | undefined | null): ImplicitScenario;
+//# sourceMappingURL=exploration.d.ts.map

package/dist/types/exploration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploration.d.ts","sourceRoot":"","sources":["../../src/types/exploration.ts"],"names":[],"mappings":"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"}

package/dist/types/exploration.js

@@ -0,0 +1,28 @@
+/**
+ * Exploration Mode runtime types (copied from eventflow-designer
+ * src/types/exploration.ts — pure, no imports). Keep in sync; the parity test
+ * guards the runtime behaviour that depends on these shapes.
+ */
+/** An empty implicit scenario — the default when nothing is seeded. */
+export const EMPTY_IMPLICIT_SCENARIO = {
+    initialState: {},
+};
+/** Narrowing type guards for the expected union. */
+export function isExpectedEvents(e) {
+    return e.events !== undefined;
+}
+export function isExpectedInformation(e) {
+    return e.view !== undefined;
+}
+/** Adapter: narrow a persisted Scenario down to the runtime-facing Implicit one. */
+export function toImplicitScenario(scenario) {
+    if (!scenario)
+        return EMPTY_IMPLICIT_SCENARIO;
+    return {
+        initialState: scenario.initialState ?? {},
+        seededEvents: scenario.seededEvents,
+        clock: scenario.clock ?? undefined,
+        interactions: scenario.interactions,
+    };
+}
+//# sourceMappingURL=exploration.js.map

package/dist/types/exploration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploration.js","sourceRoot":"","sources":["../../src/types/exploration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0FH,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAqB;IACvD,YAAY,EAAE,EAAE;CACjB,CAAC;AAqCF,oDAAoD;AACpD,MAAM,UAAU,gBAAgB,CAAC,CAAkC;IACjE,OAAQ,CAAoB,CAAC,MAAM,KAAK,SAAS,CAAC;AACpD,CAAC;AACD,MAAM,UAAU,qBAAqB,CACnC,CAAkC;IAElC,OAAQ,CAAyB,CAAC,IAAI,KAAK,SAAS,CAAC;AACvD,CAAC;AA8BD,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,QAAqC;IACtE,IAAI,CAAC,QAAQ;QAAE,OAAO,uBAAuB,CAAC;IAC9C,OAAO;QACL,YAAY,EAAE,QAAQ,CAAC,YAAY,IAAI,EAAE;QACzC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,SAAS;QAClC,YAAY,EAAE,QAAQ,CAAC,YAAY;KACpC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@proophboard/exploration-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Pure, environment-independent Exploration Mode runtime for prooph board: fold play functions, run scenarios as tests, and build the TypeScript .d.ts surfaces used to typecheck play functions. Runs in Node and the browser.",
+  "keywords": [
+    "prooph-board",
+    "event-modeling",
+    "exploration-mode",
+    "play-function",
+    "scenario",
+    "runtime"
+  ],
+  "license": "MIT",
+  "author": "prooph software GmbH",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "sucrase": "^3.35.0"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.17.0",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.