@almadar/runtime 1.2.3 → 2.0.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { B as BindingContext, T as TraitState, a as TraitDefinition, b as TransitionResult, E as EffectHandlers, c as EffectContext } from './types-LiBPiu-u.js';
-export { d as Effect, e as EventListener, I as IEventBus, R as RuntimeEvent, U as Unsubscribe } from './types-LiBPiu-u.js';
-export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, j as getIsolatedCollectionName, k as getNamespacedEvent, l as isNamespacedEvent, p as parseNamespacedEvent, m as preprocessSchema } from './OrbitalServerRuntime-Bp1YgmI1.js';
+import { B as BindingContext, T as TraitState, a as TraitDefinition, R as RuntimeConfig, b as TransitionObserver, c as TransitionResult, E as EffectHandlers, d as EffectContext, e as ExecutionEnvironment, f as EffectResult } from './types-9hbY6RWC.js';
+export { g as Effect, h as EventListener, H as HANDLER_MANIFEST, I as IEventBus, i as RuntimeEvent, U as Unsubscribe } from './types-9hbY6RWC.js';
+export { E as EntitySharingMap, a as EventBus, b as EventNamespaceMap, O as OrbitalEventRequest, c as OrbitalEventResponse, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, e as PreprocessOptions, f as PreprocessResult, g as PreprocessedSchema, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, j as getIsolatedCollectionName, k as getNamespacedEvent, l as isNamespacedEvent, p as parseNamespacedEvent, m as preprocessSchema } from './OrbitalServerRuntime-CNyOL8XD.js';
 import { EvaluationContext } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
 export { ServerBridgeConfig, ServerBridgeState } from './ServerBridge.js';
@@ -51,8 +51,11 @@ declare function containsBindings(value: unknown): boolean;
 declare function extractBindings(value: unknown): string[];
 /**
  * Create an EvaluationContext from a BindingContext.
+ *
+ * @param bindings - Binding context with entity, payload, state data
+ * @param strictBindings - When true, log warnings for undefined binding paths (RCG-01)
  */
-declare function createContextFromBindings(bindings: BindingContext): EvaluationContext;
+declare function createContextFromBindings(bindings: BindingContext, strictBindings?: boolean): EvaluationContext;
 
 /**
  * StateMachineCore - Platform-Agnostic State Machine Logic
@@ -94,6 +97,16 @@ interface ProcessEventOptions {
     payload?: Record<string, unknown>;
     /** Entity data for binding resolution */
     entityData?: Record<string, unknown>;
+    /**
+     * Guard evaluation error handling mode. (RCG-02)
+     * - "permissive": Guard errors allow the transition (default, backwards-compatible)
+     * - "strict": Guard errors block the transition
+     */
+    guardMode?: "strict" | "permissive";
+    /**
+     * When true, log warnings when bindings resolve to undefined. (RCG-01)
+     */
+    strictBindings?: boolean;
 }
 /**
  * Process an event through a trait's state machine.
@@ -145,7 +158,15 @@ declare function processEvent(options: ProcessEventOptions): TransitionResult;
 declare class StateMachineManager {
     private traits;
     private states;
-    constructor(traits?: TraitDefinition[]);
+    private config;
+    private observer?;
+    constructor(traits?: TraitDefinition[], config?: RuntimeConfig, observer?: TransitionObserver);
+    /**
+     * Set the transition observer for runtime verification.
+     * Wire this to `verificationRegistry.recordTransition()` to enable
+     * automatic verification tracking.
+     */
+    setObserver(observer: TransitionObserver): void;
     /**
      * Add a trait to the manager.
      */
@@ -206,6 +227,8 @@ interface EffectExecutorOptions {
     context: EffectContext;
     /** Enable debug logging */
     debug?: boolean;
+    /** When true, log warnings when bindings resolve to undefined (RCG-01) */
+    strictBindings?: boolean;
 }
 /**
  * EffectExecutor - Routes effects to handlers.
@@ -238,7 +261,33 @@ declare class EffectExecutor {
     private bindings;
     private context;
     private debug;
+    private strictBindings;
     constructor(options: EffectExecutorOptions);
+    /**
+     * Validate that all effect types used in a schema have handlers registered.
+     * Call this at runtime startup to catch missing handler setup immediately.
+     *
+     * @param usedEffectTypes - Effect operator names used in the loaded schemas
+     * @param environment - Execution environment for context-aware error messages
+     * @returns Array of missing handler errors (empty if all handlers are available)
+     *
+     * @example
+     * ```ts
+     * const missing = EffectExecutor.validateHandlers(
+     *   ['persist', 'render-ui', 'fetch'],
+     *   executor.getRegisteredHandlers(),
+     *   'client'
+     * );
+     * if (missing.length > 0) {
+     *   console.error('Missing handlers:', missing);
+     * }
+     * ```
+     */
+    static validateHandlers(usedEffectTypes: string[], registeredHandlers: string[], environment?: ExecutionEnvironment): string[];
+    /**
+     * Get list of effect operators that have handlers registered.
+     */
+    getRegisteredHandlers(): string[];
     /**
      * Execute a single effect.
      */
@@ -251,6 +300,14 @@ declare class EffectExecutor {
      * Execute multiple effects in parallel.
      */
     executeParallel(effects: unknown[]): Promise<void>;
+    /**
+     * Execute effects and return detailed results for each.
+     * Enables compensating transitions by reporting which effects failed.
+     *
+     * Unlike `executeAll`, this method does NOT throw on effect errors.
+     * Instead, it captures errors in the returned `EffectResult[]` array.
+     */
+    executeWithResults(effects: unknown[]): Promise<EffectResult[]>;
     private dispatch;
     private logUnsupported;
 }
@@ -351,4 +408,68 @@ interface MockPersistenceConfig {
     debug?: boolean;
 }
 
-export { BindingContext, type ClientEventBus, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, type EntityField, type EntitySchema, type MockPersistenceConfig, type ProcessEventOptions, type SlotSetter, StateMachineManager, TraitDefinition, TraitState, TransitionResult, containsBindings, createClientEffectHandlers, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent };
+/**
+ * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)
+ *
+ * Validates that listener `payloadMapping` references match the emitter's
+ * payload field names. Catches mismatches like `@payload.task_id` when the
+ * emitter defines `taskId`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Emit declaration from a trait.
+ */
+interface EmitDeclaration {
+    event: string;
+    payload?: Array<{
+        name: string;
+        type?: string;
+    }>;
+}
+/**
+ * Payload validation error.
+ */
+interface PayloadMismatch {
+    /** Listening trait name */
+    listenerTrait: string;
+    /** Emitting trait name */
+    emitterTrait: string;
+    /** Event name */
+    event: string;
+    /** The payload field referenced in the listener's payloadMapping */
+    referencedField: string;
+    /** Available fields from the emitter's payload declaration */
+    availableFields: string[];
+}
+/**
+ * Validate that all listener payloadMapping references match emitter payload fields.
+ *
+ * @param traits - All trait definitions in the schema
+ * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])
+ * @returns Array of payload mismatches (empty if all valid)
+ *
+ * @example
+ * ```ts
+ * const mismatches = validatePayloadShapes(traits, emitsMap);
+ * for (const m of mismatches) {
+ *   console.warn(
+ *     `Trait "${m.listenerTrait}" references @payload.${m.referencedField} ` +
+ *     `for event "${m.event}" but emitter "${m.emitterTrait}" only declares: ` +
+ *     `${m.availableFields.join(', ')}`
+ *   );
+ * }
+ * ```
+ */
+declare function validatePayloadShapes(traits: TraitDefinition[], emits: Map<string, EmitDeclaration[]>): PayloadMismatch[];
+/**
+ * Build emit declarations map from trait definitions.
+ * Extracts emits from transitions that use the `emit` effect.
+ *
+ * Note: This is a heuristic — it parses emit effects from transitions.
+ * For full accuracy, the schema should include explicit `emits` declarations.
+ */
+declare function buildEmitsFromTraits(traits: TraitDefinition[], explicitEmits?: Map<string, EmitDeclaration[]>): Map<string, EmitDeclaration[]>;
+
+export { BindingContext, type ClientEventBus, type CreateClientEffectHandlersOptions, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntityField, type EntitySchema, ExecutionEnvironment, type MockPersistenceConfig, type PayloadMismatch, type ProcessEventOptions, RuntimeConfig, type SlotSetter, StateMachineManager, TraitDefinition, TraitState, TransitionObserver, TransitionResult, buildEmitsFromTraits, containsBindings, createClientEffectHandlers, createContextFromBindings, createInitialTraitState, createTestExecutor, extractBindings, findInitialState, findTransition, interpolateProps, interpolateValue, normalizeEventKey, processEvent, validatePayloadShapes };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { EffectExecutor, EventBus, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-QBQSJJF6.js';
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createTestExecutor, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent } from './chunk-EOMQVFFE.js';
 
 // src/ClientEffectHandlers.ts
 function createClientEffectHandlers(options) {
@@ -35,6 +35,83 @@ function createClientEffectHandlers(options) {
   };
 }
 
-export { createClientEffectHandlers };
+// src/PayloadValidator.ts
+function validatePayloadShapes(traits, emits) {
+  const mismatches = [];
+  const emitIndex = /* @__PURE__ */ new Map();
+  for (const [traitName, declarations] of emits) {
+    for (const decl of declarations) {
+      const fields = decl.payload?.map((p) => p.name) ?? [];
+      emitIndex.set(decl.event, { traitName, fields });
+    }
+  }
+  for (const trait of traits) {
+    if (!trait.listens) continue;
+    for (const listener of trait.listens) {
+      const emitter = emitIndex.get(listener.event);
+      if (!emitter) continue;
+      if (!listener.payloadMapping) continue;
+      const payloadRefs = extractPayloadReferences(listener.payloadMapping);
+      for (const ref of payloadRefs) {
+        if (!emitter.fields.includes(ref)) {
+          mismatches.push({
+            listenerTrait: trait.name,
+            emitterTrait: emitter.traitName,
+            event: listener.event,
+            referencedField: ref,
+            availableFields: emitter.fields
+          });
+        }
+      }
+    }
+  }
+  return mismatches;
+}
+function extractPayloadReferences(mapping) {
+  const refs = [];
+  function collect(value) {
+    if (typeof value === "string") {
+      const match = value.match(/^@payload\.(\w+)$/);
+      if (match) {
+        refs.push(match[1]);
+      }
+    } else if (typeof value === "object" && value !== null) {
+      if (Array.isArray(value)) {
+        value.forEach(collect);
+      } else {
+        Object.values(value).forEach(collect);
+      }
+    }
+  }
+  Object.values(mapping).forEach(collect);
+  return [...new Set(refs)];
+}
+function buildEmitsFromTraits(traits, explicitEmits) {
+  const result = new Map(explicitEmits ?? []);
+  for (const trait of traits) {
+    if (result.has(trait.name)) continue;
+    const emitDecls = [];
+    for (const transition of trait.transitions) {
+      if (!transition.effects) continue;
+      for (const effect of transition.effects) {
+        if (!Array.isArray(effect)) continue;
+        if (effect[0] === "emit" && typeof effect[1] === "string") {
+          const event = effect[1];
+          const payloadObj = effect[2];
+          const payload = payloadObj ? Object.keys(payloadObj).map((name) => ({ name })) : void 0;
+          if (!emitDecls.some((d) => d.event === event)) {
+            emitDecls.push({ event, payload });
+          }
+        }
+      }
+    }
+    if (emitDecls.length > 0) {
+      result.set(trait.name, emitDecls);
+    }
+  }
+  return result;
+}
+
+export { buildEmitsFromTraits, createClientEffectHandlers, validatePayloadShapes };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ClientEffectHandlers.ts"],"names":[],"mappings":";;;AAwEO,SAAS,2BACZ,OAAA,EACc;AACd,EAAA,MAAM,EAAE,QAAA,EAAU,UAAA,EAAY,QAAA,EAAU,MAAA,EAAQ,eAAc,GAAI,OAAA;AAElE,EAAA,OAAO;AAAA,IACH,IAAA,EAAM,CAAC,KAAA,EAAe,OAAA,KAAsC;AACxD,MAAA,MAAM,gBAAgB,KAAA,CAAM,UAAA,CAAW,KAAK,CAAA,GAAI,KAAA,GAAQ,MAAM,KAAK,CAAA,CAAA;AACnE,MAAA,QAAA,CAAS,IAAA,CAAK,aAAA,EAAe,EAAE,OAAA,EAAS,CAAA;AAAA,IAC5C,CAAA;AAAA,IAEA,SAAS,YAAY;AACjB,MAAA,OAAA,CAAQ,KAAK,uEAAuE,CAAA;AAAA,IACxF,CAAA;AAAA,IAEA,KAAK,MAAM;AACP,MAAA,OAAA,CAAQ,KAAK,mEAAmE,CAAA;AAAA,IACpF,CAAA;AAAA,IAEA,aAAa,YAAY;AACrB,MAAA,OAAA,CAAQ,KAAK,2EAA2E,CAAA;AACxF,MAAA,OAAO,EAAC;AAAA,IACZ,CAAA;AAAA,IAEA,QAAA,EAAU,CAAC,IAAA,EAAc,OAAA,EAAkB,KAAA,KAAoC;AAC3E,MAAA,IAAI,YAAY,IAAA,EAAM;AAClB,QAAA,UAAA,CAAW,UAAU,IAAI,CAAA;AACzB,QAAA;AAAA,MACJ;AACA,MAAA,MAAM,QAAA,GAAW,aAAA,GAAgB,aAAA,CAAc,OAAO,CAAA,GAAI,OAAA;AAC1D,MAAA,UAAA,CAAW,UAAA,CAAW,IAAA,EAAM,QAAA,EAAU,KAAK,CAAA;AAAA,IAC/C,CAAA;AAAA,IAEA,QAAA,EAAU,QAAA,KAAa,CAAC,IAAA,KAAiB;AACrC,MAAA,OAAA,CAAQ,IAAA,CAAK,yDAAyD,IAAI,CAAA;AAAA,IAC9E,CAAA,CAAA;AAAA,IAEA,MAAA,EAAQ,MAAA,KAAW,CAAC,GAAA,EAAa,IAAA,KAAkB;AAC/C,MAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,+BAAA,EAAkC,IAAI,CAAA,EAAA,CAAA,EAAM,GAAG,CAAA;AAAA,IAC/D,CAAA;AAAA,GACJ;AACJ","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: Record<string, unknown>) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: Record<string, unknown>) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n    /** Entity enrichment: inject linkedEntity into entity-aware patterns */\n    enrichPattern?: (pattern: unknown) => unknown;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify, enrichPattern } = options;\n\n    return {\n        emit: (event: string, payload?: Record<string, unknown>) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: Record<string, unknown>) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            const enriched = enrichPattern ? enrichPattern(pattern) : pattern;\n            slotSetter.addPattern(slot, enriched, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n"]}
+{"version":3,"sources":["../src/ClientEffectHandlers.ts","../src/PayloadValidator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Client Effect Handlers Factory\n *\n * Creates the standard effect handler set for client-side trait execution.\n * Platform-agnostic — works with any UI framework that provides the required interfaces.\n *\n * @packageDocumentation\n */\n\nimport type { EffectHandlers } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Minimal event bus interface required by the factory.\n */\nexport interface ClientEventBus {\n    emit: (type: string, payload?: Record<string, unknown>) => void;\n}\n\n/**\n * Slot setter interface for render-ui effects.\n * The factory doesn't know about React state — it just calls this function.\n */\nexport interface SlotSetter {\n    /** Accumulate a pattern into the pending slot map */\n    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;\n    /** Mark a slot for clearing */\n    clearSlot: (slot: string) => void;\n}\n\n/**\n * Options for creating client effect handlers.\n */\nexport interface CreateClientEffectHandlersOptions {\n    /** Event bus for emit effects */\n    eventBus: ClientEventBus;\n    /** Slot setter for render-ui effects */\n    slotSetter: SlotSetter;\n    /** Navigate function for navigate effects */\n    navigate?: (path: string, params?: Record<string, unknown>) => void;\n    /** Notify function for notification effects */\n    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;\n    /** Entity enrichment: inject linkedEntity into entity-aware patterns */\n    enrichPattern?: (pattern: unknown) => unknown;\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\n/**\n * Create client-side effect handlers for trait state machine execution.\n *\n * Client handles: emit, renderUI, navigate, notify\n * Server handles: persist, set, callService (logged as warnings on client)\n *\n * @example\n * ```ts\n * const handlers = createClientEffectHandlers({\n *   eventBus,\n *   slotSetter: {\n *     addPattern: (slot, pattern, props) => pendingSlots.get(slot)?.push({ pattern, props }),\n *     clearSlot: (slot) => pendingSlots.set(slot, []),\n *   },\n *   navigate: (path) => router.push(path),\n *   notify: (msg, type) => toast[type](msg),\n * });\n * ```\n */\nexport function createClientEffectHandlers(\n    options: CreateClientEffectHandlersOptions\n): EffectHandlers {\n    const { eventBus, slotSetter, navigate, notify, enrichPattern } = options;\n\n    return {\n        emit: (event: string, payload?: Record<string, unknown>) => {\n            const prefixedEvent = event.startsWith('UI:') ? event : `UI:${event}`;\n            eventBus.emit(prefixedEvent, { payload });\n        },\n\n        persist: async () => {\n            console.warn('[ClientEffectHandlers] persist is server-side only, ignored on client');\n        },\n\n        set: () => {\n            console.warn('[ClientEffectHandlers] set is server-side only, ignored on client');\n        },\n\n        callService: async () => {\n            console.warn('[ClientEffectHandlers] callService is server-side only, ignored on client');\n            return {};\n        },\n\n        renderUI: (slot: string, pattern: unknown, props?: Record<string, unknown>) => {\n            if (pattern === null) {\n                slotSetter.clearSlot(slot);\n                return;\n            }\n            const enriched = enrichPattern ? enrichPattern(pattern) : pattern;\n            slotSetter.addPattern(slot, enriched, props);\n        },\n\n        navigate: navigate ?? ((path: string) => {\n            console.warn('[ClientEffectHandlers] No navigate handler, ignoring:', path);\n        }),\n\n        notify: notify ?? ((msg: string, type?: string) => {\n            console.log(`[ClientEffectHandlers] notify (${type}):`, msg);\n        }),\n    };\n}\n","/**\n * PayloadValidator - Cross-Trait Payload Shape Validation (RCG-10)\n *\n * Validates that listener `payloadMapping` references match the emitter's\n * payload field names. Catches mismatches like `@payload.task_id` when the\n * emitter defines `taskId`.\n *\n * @packageDocumentation\n */\n\nimport type { TraitDefinition } from './types.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Emit declaration from a trait.\n */\ninterface EmitDeclaration {\n    event: string;\n    payload?: Array<{ name: string; type?: string }>;\n}\n\n/**\n * Payload validation error.\n */\nexport interface PayloadMismatch {\n    /** Listening trait name */\n    listenerTrait: string;\n    /** Emitting trait name */\n    emitterTrait: string;\n    /** Event name */\n    event: string;\n    /** The payload field referenced in the listener's payloadMapping */\n    referencedField: string;\n    /** Available fields from the emitter's payload declaration */\n    availableFields: string[];\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Validate that all listener payloadMapping references match emitter payload fields.\n *\n * @param traits - All trait definitions in the schema\n * @param emits - Emit declarations per trait (traitName → EmitDeclaration[])\n * @returns Array of payload mismatches (empty if all valid)\n *\n * @example\n * ```ts\n * const mismatches = validatePayloadShapes(traits, emitsMap);\n * for (const m of mismatches) {\n *   console.warn(\n *     `Trait \"${m.listenerTrait}\" references @payload.${m.referencedField} ` +\n *     `for event \"${m.event}\" but emitter \"${m.emitterTrait}\" only declares: ` +\n *     `${m.availableFields.join(', ')}`\n *   );\n * }\n * ```\n */\nexport function validatePayloadShapes(\n    traits: TraitDefinition[],\n    emits: Map<string, EmitDeclaration[]>\n): PayloadMismatch[] {\n    const mismatches: PayloadMismatch[] = [];\n\n    // Build event→emitter lookup: event name → { traitName, payload fields }\n    const emitIndex = new Map<string, { traitName: string; fields: string[] }>();\n    for (const [traitName, declarations] of emits) {\n        for (const decl of declarations) {\n            const fields = decl.payload?.map((p) => p.name) ?? [];\n            emitIndex.set(decl.event, { traitName, fields });\n        }\n    }\n\n    // Check each listener's payloadMapping references\n    for (const trait of traits) {\n        if (!trait.listens) continue;\n\n        for (const listener of trait.listens) {\n            const emitter = emitIndex.get(listener.event);\n            if (!emitter) continue; // No emitter found — separate validation concern\n\n            if (!listener.payloadMapping) continue;\n\n            // Extract @payload.X references from payloadMapping values\n            const payloadRefs = extractPayloadReferences(listener.payloadMapping);\n\n            for (const ref of payloadRefs) {\n                if (!emitter.fields.includes(ref)) {\n                    mismatches.push({\n                        listenerTrait: trait.name,\n                        emitterTrait: emitter.traitName,\n                        event: listener.event,\n                        referencedField: ref,\n                        availableFields: emitter.fields,\n                    });\n                }\n            }\n        }\n    }\n\n    return mismatches;\n}\n\n/**\n * Extract payload field references from a payloadMapping object.\n * Finds all `@payload.fieldName` patterns and returns the field names.\n */\nfunction extractPayloadReferences(mapping: Record<string, unknown>): string[] {\n    const refs: string[] = [];\n\n    function collect(value: unknown): void {\n        if (typeof value === 'string') {\n            const match = value.match(/^@payload\\.(\\w+)$/);\n            if (match) {\n                refs.push(match[1]);\n            }\n        } else if (typeof value === 'object' && value !== null) {\n            if (Array.isArray(value)) {\n                value.forEach(collect);\n            } else {\n                Object.values(value as Record<string, unknown>).forEach(collect);\n            }\n        }\n    }\n\n    Object.values(mapping).forEach(collect);\n    return [...new Set(refs)];\n}\n\n/**\n * Build emit declarations map from trait definitions.\n * Extracts emits from transitions that use the `emit` effect.\n *\n * Note: This is a heuristic — it parses emit effects from transitions.\n * For full accuracy, the schema should include explicit `emits` declarations.\n */\nexport function buildEmitsFromTraits(\n    traits: TraitDefinition[],\n    explicitEmits?: Map<string, EmitDeclaration[]>\n): Map<string, EmitDeclaration[]> {\n    // Start with explicit emits if provided\n    const result = new Map<string, EmitDeclaration[]>(explicitEmits ?? []);\n\n    for (const trait of traits) {\n        if (result.has(trait.name)) continue; // Explicit declarations take precedence\n\n        const emitDecls: EmitDeclaration[] = [];\n        for (const transition of trait.transitions) {\n            if (!transition.effects) continue;\n\n            for (const effect of transition.effects) {\n                if (!Array.isArray(effect)) continue;\n                if (effect[0] === 'emit' && typeof effect[1] === 'string') {\n                    const event = effect[1] as string;\n                    // Payload is in effect[2] if present\n                    const payloadObj = effect[2] as Record<string, unknown> | undefined;\n                    const payload = payloadObj\n                        ? Object.keys(payloadObj).map((name) => ({ name }))\n                        : undefined;\n\n                    // Avoid duplicates\n                    if (!emitDecls.some((d) => d.event === event)) {\n                        emitDecls.push({ event, payload });\n                    }\n                }\n            }\n        }\n\n        if (emitDecls.length > 0) {\n            result.set(trait.name, emitDecls);\n        }\n    }\n\n    return result;\n}\n"]}

package/dist/{types-LiBPiu-u.d.ts → types-9hbY6RWC.d.ts}

@@ -93,6 +93,11 @@ interface TraitDefinition {
         event: string;
         guard?: unknown;
         effects?: unknown[];
+        /** Compensating transition when effects fail (RCG-04) */
+        onEffectError?: {
+            to: string;
+            effects?: unknown[];
+        };
     }>;
     /** Cross-trait event listeners (optional) */
     listens?: Array<{
@@ -110,8 +115,8 @@ interface TraitDefinition {
 interface EffectHandlers {
     /** Emit an event to the event bus */
     emit: (event: string, payload?: Record<string, unknown>) => void;
-    /** Persist data (create/update/delete) */
-    persist: (action: 'create' | 'update' | 'delete', entityType: string, data?: Record<string, unknown>) => Promise<void>;
+    /** Persist data (create/update/delete/batch) */
+    persist: (action: 'create' | 'update' | 'delete' | 'batch', entityType: string, data?: Record<string, unknown>) => Promise<void>;
     /** Set a field value on an entity */
     set: (entityId: string, field: string, value: unknown) => void;
     /** Call an external service */
@@ -173,5 +178,84 @@ interface EffectContext {
     /** Entity ID (if available) */
     entityId?: string;
 }
+/**
+ * Result of executing a single effect, with status tracking.
+ */
+interface EffectResult {
+    /** Effect operator (e.g., "persist", "render-ui") */
+    type: string;
+    /** Effect arguments */
+    args: unknown[];
+    /** Whether the effect executed successfully */
+    status: "executed" | "failed" | "skipped";
+    /** Error message if failed */
+    error?: string;
+    /** Execution duration in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Runtime configuration for strictness and safety modes.
+ *
+ * These options control how the runtime handles edge cases:
+ * - `strictBindings`: Log warnings when bindings resolve to undefined (RCG-01)
+ * - `guardMode`: Control whether guard errors block or allow transitions (RCG-02)
+ * - `maxEventDepth`: Prevent infinite event loops (RCG-05)
+ */
+interface RuntimeConfig {
+    /**
+     * When true, log warnings when bindings like @entity.field resolve to undefined.
+     * Helps detect typos and missing fields early. (RCG-01)
+     * @default false
+     */
+    strictBindings?: boolean;
+    /**
+     * Guard evaluation error handling mode. (RCG-02)
+     * - "permissive": Guard errors allow the transition (current default behavior)
+     * - "strict": Guard errors block the transition
+     * @default "permissive"
+     */
+    guardMode?: "strict" | "permissive";
+    /**
+     * Maximum event emission depth before triggering circuit breaker. (RCG-05)
+     * Prevents infinite loops from circular emit/listen chains.
+     * @default 10
+     */
+    maxEventDepth?: number;
+}
+/**
+ * Execution context for handler manifest validation.
+ * Defines which effect handlers should be available in each environment.
+ */
+type ExecutionEnvironment = "client" | "server" | "test" | "ssr";
+/**
+ * Observer interface for recording transition and effect traces.
+ * Implement this to wire in the verificationRegistry or other monitoring tools.
+ *
+ * The runtime calls these hooks automatically when transitions execute and
+ * effects complete, enabling runtime verification without tight coupling.
+ */
+interface TransitionObserver {
+    /**
+     * Called after a transition is processed (whether or not it executed).
+     */
+    onTransition(trace: {
+        traitName: string;
+        from: string;
+        to: string;
+        event: string;
+        guardResult?: boolean;
+        effects: Array<{
+            type: string;
+            args: unknown[];
+            status: "executed" | "failed" | "skipped";
+            error?: string;
+            durationMs?: number;
+        }>;
+    }): void;
+}
+/**
+ * Maps execution environments to their available effect handlers.
+ */
+declare const HANDLER_MANIFEST: Record<ExecutionEnvironment, string[]>;
 
-export type { BindingContext as B, EffectHandlers as E, IEventBus as I, RuntimeEvent as R, TraitState as T, Unsubscribe as U, TraitDefinition as a, TransitionResult as b, EffectContext as c, Effect as d, EventListener as e };
+export { type BindingContext as B, type EffectHandlers as E, HANDLER_MANIFEST as H, type IEventBus as I, type RuntimeConfig as R, type TraitState as T, type Unsubscribe as U, type TraitDefinition as a, type TransitionObserver as b, type TransitionResult as c, type EffectContext as d, type ExecutionEnvironment as e, type EffectResult as f, type Effect as g, type EventListener as h, type RuntimeEvent as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "1.2.3",
+  "version": "2.0.0",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,9 +27,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@faker-js/faker": "^9.3.0",
-    "@almadar/evaluator": "1.0.16",
-    "@almadar/core": "1.0.18"
+    "@almadar/evaluator": ">=2.0.0",
+    "@almadar/core": ">=2.0.0",
+    "@faker-js/faker": "^9.3.0"
   },
   "peerDependencies": {
     "express": "^4.0.0"
@@ -45,7 +45,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/almadar-io/almadar.git",
-    "directory": "packages/almadar-runtime"
+    "directory": "docs/packages/runtime"
   },
   "license": "MIT",
   "keywords": [
@@ -54,6 +54,7 @@
     "orbital",
     "interpreter"
   ],
+  "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",