@almadar/runtime 1.2.3 → 2.0.0

package/dist/{chunk-QBQSJJF6.js → chunk-EOMQVFFE.js}

@@ -6,13 +6,28 @@ import { OrbitalSchemaSchema, isEntityReference, parseEntityRef, parseImportedTr
 var EventBus = class {
   listeners = /* @__PURE__ */ new Map();
   debug;
+  /** Maximum recursion depth before circuit breaker activates (RCG-05) */
+  maxDepth;
+  /** Current emission depth for circular loop detection */
+  depth = 0;
   constructor(options = {}) {
     this.debug = options.debug ?? false;
+    this.maxDepth = options.maxDepth ?? 10;
   }
   /**
-   * Emit an event to all registered listeners
+   * Emit an event to all registered listeners.
+   *
+   * Includes circuit breaker (RCG-05): if emit is called recursively
+   * beyond `maxDepth`, the event is dropped and an error is logged.
+   * This prevents infinite loops from circular emit/listen chains.
    */
   emit(type, payload, source) {
+    if (this.depth >= this.maxDepth) {
+      console.error(
+        `[EventBus] Circular event loop detected: "${type}" at depth ${this.depth}. Event dropped to prevent infinite recursion. Increase maxDepth (currently ${this.maxDepth}) if this is intentional.`
+      );
+      return;
+    }
     const event = {
       type,
       payload,
@@ -23,32 +38,37 @@ var EventBus = class {
     const listenerCount = listeners?.size ?? 0;
     if (this.debug) {
       if (listenerCount > 0) {
-        console.log(`[EventBus] Emit: ${type} \u2192 ${listenerCount} listener(s)`, payload);
+        console.log(`[EventBus] Emit: ${type} \u2192 ${listenerCount} listener(s) (depth: ${this.depth})`, payload);
       } else {
         console.warn(`[EventBus] Emit: ${type} (NO LISTENERS)`, payload);
       }
     }
-    if (listeners) {
-      const listenersCopy = Array.from(listeners);
-      for (const listener of listenersCopy) {
-        try {
-          listener(event);
-        } catch (error) {
-          console.error(`[EventBus] Error in listener for '${type}':`, error);
-        }
-      }
-    }
-    if (type !== "*") {
-      const wildcardListeners = this.listeners.get("*");
-      if (wildcardListeners) {
-        for (const listener of Array.from(wildcardListeners)) {
+    this.depth++;
+    try {
+      if (listeners) {
+        const listenersCopy = Array.from(listeners);
+        for (const listener of listenersCopy) {
           try {
             listener(event);
           } catch (error) {
-            console.error(`[EventBus] Error in wildcard listener:`, error);
+            console.error(`[EventBus] Error in listener for '${type}':`, error);
           }
         }
       }
+      if (type !== "*") {
+        const wildcardListeners = this.listeners.get("*");
+        if (wildcardListeners) {
+          for (const listener of Array.from(wildcardListeners)) {
+            try {
+              listener(event);
+            } catch (error) {
+              console.error(`[EventBus] Error in wildcard listener:`, error);
+            }
+          }
+        }
+      }
+    } finally {
+      this.depth--;
     }
   }
   /**
@@ -251,12 +271,16 @@ function extractBindings(value) {
   collect(value);
   return [...new Set(bindings)];
 }
-function createContextFromBindings(bindings) {
-  return createMinimalContext(
+function createContextFromBindings(bindings, strictBindings) {
+  const ctx = createMinimalContext(
     bindings.entity || {},
     bindings.payload || {},
     bindings.state || "idle"
   );
+  if (strictBindings) {
+    ctx.strictBindings = true;
+  }
+  return ctx;
 }
 function findInitialState(trait) {
   if (!trait.states || trait.states.length === 0) {
@@ -292,7 +316,15 @@ function normalizeEventKey(eventKey) {
   return eventKey.startsWith("UI:") ? eventKey.slice(3) : eventKey;
 }
 function processEvent(options) {
-  const { traitState, trait, eventKey, payload, entityData } = options;
+  const {
+    traitState,
+    trait,
+    eventKey,
+    payload,
+    entityData,
+    guardMode = "permissive",
+    strictBindings = false
+  } = options;
   const normalizedEvent = normalizeEventKey(eventKey);
   const transition = findTransition(trait, traitState.currentState, normalizedEvent);
   if (!transition) {
@@ -308,7 +340,7 @@ function processEvent(options) {
       entity: entityData,
       payload,
       state: traitState.currentState
-    });
+    }, strictBindings);
     try {
       const guardPasses = evaluateGuard(
         transition.guard,
@@ -329,6 +361,24 @@ function processEvent(options) {
         };
       }
     } catch (error) {
+      if (guardMode === "strict") {
+        console.error(
+          `[StateMachineCore] Guard error blocks transition ${traitState.currentState}\u2192${transition.to} (${normalizedEvent}):`,
+          error
+        );
+        return {
+          executed: false,
+          newState: traitState.currentState,
+          previousState: traitState.currentState,
+          effects: [],
+          transition: {
+            from: traitState.currentState,
+            to: transition.to,
+            event: normalizedEvent
+          },
+          guardResult: false
+        };
+      }
       console.error("[StateMachineCore] Guard evaluation error:", error);
     }
   }
@@ -348,11 +398,23 @@ function processEvent(options) {
 var StateMachineManager = class {
   traits = /* @__PURE__ */ new Map();
   states = /* @__PURE__ */ new Map();
-  constructor(traits = []) {
+  config;
+  observer;
+  constructor(traits = [], config = {}, observer) {
+    this.config = config;
+    this.observer = observer;
     for (const trait of traits) {
       this.addTrait(trait);
     }
   }
+  /**
+   * Set the transition observer for runtime verification.
+   * Wire this to `verificationRegistry.recordTransition()` to enable
+   * automatic verification tracking.
+   */
+  setObserver(observer) {
+    this.observer = observer;
+  }
   /**
    * Add a trait to the manager.
    */
@@ -403,7 +465,9 @@ var StateMachineManager = class {
         trait,
         eventKey,
         payload,
-        entityData
+        entityData,
+        guardMode: this.config.guardMode,
+        strictBindings: this.config.strictBindings
       });
       if (result.executed) {
         this.states.set(traitName, {
@@ -414,6 +478,17 @@ var StateMachineManager = class {
           context: { ...traitState.context, ...payload }
         });
         results.push({ traitName, result });
+        if (this.observer && result.transition) {
+          this.observer.onTransition({
+            traitName,
+            from: result.transition.from,
+            to: result.transition.to,
+            event: result.transition.event,
+            guardResult: result.guardResult,
+            // Effects will be traced when executed — placeholder here
+            effects: []
+          });
+        }
       }
     }
     return results;
@@ -437,6 +512,27 @@ var StateMachineManager = class {
   }
 };
 
+// src/types.ts
+var HANDLER_MANIFEST = {
+  client: ["render-ui", "render", "navigate", "notify", "emit", "set", "log"],
+  server: ["persist", "fetch", "call-service", "emit", "set", "spawn", "despawn", "log"],
+  test: [
+    "render-ui",
+    "render",
+    "navigate",
+    "notify",
+    "emit",
+    "set",
+    "persist",
+    "fetch",
+    "call-service",
+    "spawn",
+    "despawn",
+    "log"
+  ],
+  ssr: ["render-ui", "render", "fetch", "emit", "set", "log"]
+};
+
 // src/EffectExecutor.ts
 function parseEffect(effect) {
   if (!Array.isArray(effect) || effect.length === 0) {
@@ -448,8 +544,8 @@ function parseEffect(effect) {
   }
   return { operator, args };
 }
-function resolveArgs(args, bindings) {
-  const ctx = createContextFromBindings(bindings);
+function resolveArgs(args, bindings, strictBindings) {
+  const ctx = createContextFromBindings(bindings, strictBindings);
   return args.map((arg) => interpolateValue(arg, ctx));
 }
 var EffectExecutor = class {
@@ -457,11 +553,77 @@ var EffectExecutor = class {
   bindings;
   context;
   debug;
+  strictBindings;
   constructor(options) {
     this.handlers = options.handlers;
     this.bindings = options.bindings;
     this.context = options.context;
     this.debug = options.debug ?? false;
+    this.strictBindings = options.strictBindings ?? false;
+  }
+  // ==========================================================================
+  // Handler Manifest Validation (RCG-03)
+  // ==========================================================================
+  /**
+   * 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, registeredHandlers, environment) {
+    const errors = [];
+    const expectedHandlers = environment ? HANDLER_MANIFEST[environment] : void 0;
+    for (const effectType of usedEffectTypes) {
+      if (!registeredHandlers.includes(effectType)) {
+        let message = `Effect "${effectType}" is used in schema but no handler is registered.`;
+        if (expectedHandlers && !expectedHandlers.includes(effectType)) {
+          message += ` Effect "${effectType}" is not expected in "${environment}" environment.`;
+        }
+        errors.push(message);
+      }
+    }
+    return errors;
+  }
+  /**
+   * Get list of effect operators that have handlers registered.
+   */
+  getRegisteredHandlers() {
+    const registered = [];
+    const handlerMap = {
+      "emit": this.handlers.emit,
+      "persist": this.handlers.persist,
+      "set": this.handlers.set,
+      "call-service": this.handlers.callService,
+      "fetch": this.handlers.fetch,
+      "spawn": this.handlers.spawn,
+      "despawn": this.handlers.despawn,
+      "render-ui": this.handlers.renderUI,
+      "render": this.handlers.renderUI,
+      "navigate": this.handlers.navigate,
+      "notify": this.handlers.notify,
+      "log": this.handlers.log
+    };
+    for (const [name, handler] of Object.entries(handlerMap)) {
+      if (handler) {
+        registered.push(name);
+      }
+    }
+    registered.push("do", "when");
+    return registered;
   }
   /**
    * Execute a single effect.
@@ -476,7 +638,7 @@ var EffectExecutor = class {
     }
     const { operator, args } = parsed;
     const isCompound = operator === "do" || operator === "when";
-    const resolvedArgs = isCompound ? args : resolveArgs(args, this.bindings);
+    const resolvedArgs = isCompound ? args : resolveArgs(args, this.bindings, this.strictBindings);
     if (this.debug) {
       console.log("[EffectExecutor] Executing:", operator, resolvedArgs);
     }
@@ -502,6 +664,54 @@ var EffectExecutor = class {
     await Promise.all(effects.map((effect) => this.execute(effect)));
   }
   // ==========================================================================
+  // Effect Execution with Results (RCG-04)
+  // ==========================================================================
+  /**
+   * 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.
+   */
+  async executeWithResults(effects) {
+    const results = [];
+    for (const effect of effects) {
+      const parsed = parseEffect(effect);
+      if (!parsed) {
+        results.push({
+          type: "unknown",
+          args: [],
+          status: "skipped",
+          error: "Invalid effect format"
+        });
+        continue;
+      }
+      const start = Date.now();
+      const { operator, args: rawArgs } = parsed;
+      const isCompound = operator === "do" || operator === "when";
+      const resolvedArgs = isCompound ? rawArgs : resolveArgs(rawArgs, this.bindings, this.strictBindings);
+      try {
+        await this.dispatch(operator, resolvedArgs);
+        results.push({
+          type: operator,
+          args: resolvedArgs,
+          status: "executed",
+          durationMs: Date.now() - start
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        results.push({
+          type: operator,
+          args: resolvedArgs,
+          status: "failed",
+          error: errorMessage,
+          durationMs: Date.now() - start
+        });
+      }
+    }
+    return results;
+  }
+  // ==========================================================================
   // Effect Dispatch
   // ==========================================================================
   async dispatch(operator, args) {
@@ -520,9 +730,14 @@ var EffectExecutor = class {
       }
       case "persist": {
         const action = args[0];
-        const entityType = args[1];
-        const data = args[2];
-        await this.handlers.persist(action, entityType, data);
+        if (action === "batch") {
+          const operations = args[1];
+          await this.handlers.persist("batch", "", { operations });
+        } else {
+          const entityType = args[1];
+          const data = args[2];
+          await this.handlers.persist(action, entityType, data);
+        }
         break;
       }
       case "call-service": {
@@ -1867,6 +2082,6 @@ function parseNamespacedEvent(eventName) {
   return { event: eventName };
 }
 
-export { EffectExecutor, EventBus, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent };
-//# sourceMappingURL=chunk-QBQSJJF6.js.map
-//# sourceMappingURL=chunk-QBQSJJF6.js.map
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, StateMachineManager, containsBindings, createContextFromBindings, createInitialTraitState, createTestExecutor, createUnifiedLoader, extractBindings, findInitialState, findTransition, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isNamespacedEvent, normalizeEventKey, parseNamespacedEvent, preprocessSchema, processEvent };
+//# sourceMappingURL=chunk-EOMQVFFE.js.map
+//# sourceMappingURL=chunk-EOMQVFFE.js.map