@almadar/runtime 3.1.1 → 3.1.3

package/dist/{OrbitalServerRuntime-QXgOGiS8.d.ts → OrbitalServerRuntime-DWJYcIJG.d.ts}

@@ -96,6 +96,11 @@ declare function findInitialState(trait: TraitDefinition): string;
 declare function createInitialTraitState(trait: TraitDefinition): TraitState;
 /**
  * Find a matching transition from the current state for the given event.
+ *
+ * **Guard-unaware**: returns the first transition matching `from` /
+ * `event` regardless of any attached guard. Use `findMatchingTransitions`
+ * when multiple sibling transitions share the same `from`/`event` and
+ * disambiguate by guard.
  */
 declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string): TraitDefinition['transitions'][0] | undefined;
 /**
@@ -164,6 +169,19 @@ interface ProcessEventOptions {
 declare function processEvent(options: ProcessEventOptions): TransitionResult;
 declare class StateMachineManager {
     private traits;
+    /**
+     * State map keyed by `${traitName}::${entityId | __singleton__}`.
+     *
+     * Each entity instance of an orbital gets its own copy of every
+     * trait's state machine. This is what enables N parallel subagents
+     * (one OrbitalProcess row per dispatched orbital) to all run their
+     * own Build/Validate/Fix cycle without colliding on shared trait
+     * state — the original cause of GAP-AGB-2.
+     *
+     * Initial state is created lazily on first event for each scope, so
+     * adding a trait does not pre-allocate state for every potential
+     * entity (and there's no need to know entity ids up front).
+     */
     private states;
     private config;
     private observer?;
@@ -184,18 +202,35 @@ declare class StateMachineManager {
      * Remove a trait from the manager.
      */
     removeTrait(traitName: string): void;
+    /**
+     * Get-or-init the state row for a (trait, entityId) pair.
+     * Returns undefined if the trait isn't registered.
+     */
+    private getOrInitState;
     /**
      * Get current state for a trait.
+     *
+     * For single-entity orbitals, omit `entityId` — returns the singleton
+     * scope. For multi-entity orbitals (e.g. agent OrbitalSubagent), pass
+     * the entity row id to look up that specific instance's state.
      */
-    getState(traitName: string): TraitState | undefined;
+    getState(traitName: string, entityId?: string): TraitState | undefined;
     /**
-     * Get all current states.
+     * Get a flat traitName→state map. For multi-entity orbitals this
+     * returns one entry per trait collapsed onto the singleton scope (or
+     * the first observed scope if singleton is empty). Use
+     * `getAllStatesByScope()` to get the full per-entity view.
      */
     getAllStates(): Map<string, TraitState>;
+    /**
+     * Get every per-entity state row, grouped by trait. Useful for
+     * inspecting parallel subagent state.
+     */
+    getAllStatesByScope(): Map<string, Map<string, TraitState>>;
     /**
      * Check if a trait can handle an event from its current state.
      */
-    canHandleEvent(traitName: string, eventKey: string): boolean;
+    canHandleEvent(traitName: string, eventKey: string, entityId?: string): boolean;
     /**
      * Send an event to all traits.
      *
@@ -214,31 +249,28 @@ declare class StateMachineManager {
      */
     enqueueEvent(eventKey: string, payload?: EventPayload, entityData?: EntityRow): void;
     /**
-     * Drain a single trait's event queue, processing events sequentially.
-     *
-     * This is the core actor loop: each event is fully processed (including
-     * awaiting all effects) before the next event is dequeued. If the queue
-     * is already being drained for this trait, this call is a no-op (the
-     * running drain will pick up newly enqueued events).
-     *
-     * @param traitName - Which trait's queue to drain
-     * @param executeEffects - Async callback to run effects for a successful transition
+     * Drain a single (trait, entity) pair's event queue, processing
+     * events sequentially. Pass `entityId` to drain a specific entity
+     * instance; omit it to drain the singleton scope.
      */
-    drainQueue(traitName: string, executeEffects: (traitName: string, result: TransitionResult, payload?: EventPayload) => Promise<void>): Promise<void>;
+    drainQueue(traitName: string, executeEffects: (traitName: string, result: TransitionResult, payload?: EventPayload) => Promise<void>, entityId?: string): Promise<void>;
     /**
      * Check whether a trait's queue is currently being drained.
      */
-    isProcessing(traitName: string): boolean;
+    isProcessing(traitName: string, entityId?: string): boolean;
     /**
      * Get the number of pending events in a trait's queue.
      */
-    getQueueLength(traitName: string): number;
+    getQueueLength(traitName: string, entityId?: string): number;
     /**
      * Reset a trait to its initial state.
+     *
+     * If `entityId` is provided, resets only that entity's scope.
+     * Otherwise resets every entity scope known for the trait.
      */
-    resetTrait(traitName: string): void;
+    resetTrait(traitName: string, entityId?: string): void;
     /**
-     * Reset all traits to initial states.
+     * Reset all traits to initial states (every entity scope).
      */
     resetAll(): void;
 }

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { v as EffectResult, L as LoaderConfig, w as LocalPersistenceAdapter, O as OrbitalEventRequest, c as OrbitalEventResponse, x as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, y as RuntimeTraitTick, z as createOrbitalServerRuntime } from './OrbitalServerRuntime-QXgOGiS8.js';
+export { v as EffectResult, L as LoaderConfig, w as LocalPersistenceAdapter, O as OrbitalEventRequest, c as OrbitalEventResponse, x as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, y as RuntimeTraitTick, z as createOrbitalServerRuntime } from './OrbitalServerRuntime-DWJYcIJG.js';
 import './types-CM6txTNy.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,4 +1,4 @@
-import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-GU35X5AW.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-QQIRPNHH.js';
 import './chunk-PZ5AY32C.js';
 import { Router } from 'express';
 import * as fs from 'fs';

package/dist/{chunk-GU35X5AW.js → chunk-QQIRPNHH.js}

@@ -304,17 +304,20 @@ function createInitialTraitState(trait) {
     context: {}
   };
 }
-function findTransition(trait, currentState, eventKey) {
+function findMatchingTransitions(trait, currentState, eventKey) {
   if (!trait.transitions || trait.transitions.length === 0) {
-    return void 0;
+    return [];
   }
-  return trait.transitions.find((t) => {
+  return trait.transitions.filter((t) => {
     if (Array.isArray(t.from)) {
       return t.from.includes(currentState) && t.event === eventKey;
     }
     return t.from === currentState && t.event === eventKey;
   });
 }
+function findTransition(trait, currentState, eventKey) {
+  return findMatchingTransitions(trait, currentState, eventKey)[0];
+}
 function normalizeEventKey(eventKey) {
   if (!eventKey) return "";
   return eventKey.startsWith("UI:") ? eventKey.slice(3) : eventKey;
@@ -331,8 +334,8 @@ function processEvent(options) {
     contextExtensions
   } = options;
   const normalizedEvent = normalizeEventKey(eventKey);
-  const transition = findTransition(trait, traitState.currentState, normalizedEvent);
-  if (!transition) {
+  const candidates = findMatchingTransitions(trait, traitState.currentState, normalizedEvent);
+  if (candidates.length === 0) {
     smLog.debug("noTransition", { trait: trait.name, event: normalizedEvent, currentState: traitState.currentState });
     return {
       executed: false,
@@ -341,8 +344,22 @@ function processEvent(options) {
       effects: []
     };
   }
-  smLog.debug("processEvent", { trait: trait.name, event: normalizedEvent, currentState: traitState.currentState, to: transition.to });
-  if (transition.guard) {
+  let lastFailedGuardTransition;
+  for (const transition of candidates) {
+    smLog.debug("processEvent", { trait: trait.name, event: normalizedEvent, currentState: traitState.currentState, to: transition.to });
+    if (!transition.guard) {
+      return {
+        executed: true,
+        newState: transition.to,
+        previousState: traitState.currentState,
+        effects: transition.effects || [],
+        transition: {
+          from: traitState.currentState,
+          to: transition.to,
+          event: normalizedEvent
+        }
+      };
+    }
     const ctx = createContextFromBindings({
       entity: entityData,
       payload,
@@ -354,20 +371,21 @@ function processEvent(options) {
         ctx
       );
       smLog.debug("guard:evaluate", { trait: trait.name, event: normalizedEvent, guardResult: guardPasses });
-      if (!guardPasses) {
+      if (guardPasses) {
         return {
-          executed: false,
-          newState: traitState.currentState,
+          executed: true,
+          newState: transition.to,
           previousState: traitState.currentState,
-          effects: [],
+          effects: transition.effects || [],
           transition: {
             from: traitState.currentState,
             to: transition.to,
             event: normalizedEvent
           },
-          guardResult: false
+          guardResult: true
         };
       }
+      lastFailedGuardTransition = transition;
     } catch (error) {
       if (guardMode === "strict") {
         console.error(
@@ -388,27 +406,62 @@ function processEvent(options) {
         };
       }
       console.error("[StateMachineCore] Guard evaluation error:", error);
+      return {
+        executed: true,
+        newState: transition.to,
+        previousState: traitState.currentState,
+        effects: transition.effects || [],
+        transition: {
+          from: traitState.currentState,
+          to: transition.to,
+          event: normalizedEvent
+        },
+        guardResult: true
+      };
     }
   }
   return {
-    executed: true,
-    newState: transition.to,
+    executed: false,
+    newState: traitState.currentState,
     previousState: traitState.currentState,
-    effects: transition.effects || [],
-    transition: {
+    effects: [],
+    transition: lastFailedGuardTransition ? {
       from: traitState.currentState,
-      to: transition.to,
+      to: lastFailedGuardTransition.to,
       event: normalizedEvent
-    },
-    guardResult: transition.guard ? true : void 0
+    } : void 0,
+    guardResult: false
   };
 }
+var SINGLETON_SCOPE = "__singleton__";
+function scopeOf(entityData) {
+  const id = entityData && entityData["id"];
+  return id ?? SINGLETON_SCOPE;
+}
+function compositeKey(traitName, scope) {
+  return `${traitName}::${scope}`;
+}
 var StateMachineManager = class {
   traits = /* @__PURE__ */ new Map();
+  /**
+   * State map keyed by `${traitName}::${entityId | __singleton__}`.
+   *
+   * Each entity instance of an orbital gets its own copy of every
+   * trait's state machine. This is what enables N parallel subagents
+   * (one OrbitalProcess row per dispatched orbital) to all run their
+   * own Build/Validate/Fix cycle without colliding on shared trait
+   * state — the original cause of GAP-AGB-2.
+   *
+   * Initial state is created lazily on first event for each scope, so
+   * adding a trait does not pre-allocate state for every potential
+   * entity (and there's no need to know entity ids up front).
+   */
   states = /* @__PURE__ */ new Map();
   config;
   observer;
-  // Actor-model per-trait queues
+  // Actor-model queues, also keyed by `${traitName}::${entityId}` so
+  // each entity gets its own actor loop and concurrent subagents do
+  // not serialize through a shared queue.
   queues = /* @__PURE__ */ new Map();
   processing = /* @__PURE__ */ new Set();
   constructor(traits = [], config = {}, observer) {
@@ -431,33 +484,101 @@ var StateMachineManager = class {
    */
   addTrait(trait) {
     this.traits.set(trait.name, trait);
-    this.states.set(trait.name, createInitialTraitState(trait));
   }
   /**
    * Remove a trait from the manager.
    */
   removeTrait(traitName) {
     this.traits.delete(traitName);
-    this.states.delete(traitName);
+    const prefix = `${traitName}::`;
+    for (const key of [...this.states.keys()]) {
+      if (key.startsWith(prefix)) this.states.delete(key);
+    }
+    for (const key of [...this.queues.keys()]) {
+      if (key.startsWith(prefix)) this.queues.delete(key);
+    }
+    for (const key of [...this.processing]) {
+      if (key.startsWith(prefix)) this.processing.delete(key);
+    }
+  }
+  /**
+   * Get-or-init the state row for a (trait, entityId) pair.
+   * Returns undefined if the trait isn't registered.
+   */
+  getOrInitState(traitName, scope) {
+    const trait = this.traits.get(traitName);
+    if (!trait) return void 0;
+    const key = compositeKey(traitName, scope);
+    let state = this.states.get(key);
+    if (!state) {
+      state = createInitialTraitState(trait);
+      this.states.set(key, state);
+    }
+    return state;
   }
   /**
    * Get current state for a trait.
+   *
+   * For single-entity orbitals, omit `entityId` — returns the singleton
+   * scope. For multi-entity orbitals (e.g. agent OrbitalSubagent), pass
+   * the entity row id to look up that specific instance's state.
    */
-  getState(traitName) {
-    return this.states.get(traitName);
+  getState(traitName, entityId) {
+    const scope = entityId ?? SINGLETON_SCOPE;
+    const key = compositeKey(traitName, scope);
+    const existing = this.states.get(key);
+    if (existing) return existing;
+    return this.getOrInitState(traitName, scope);
   }
   /**
-   * Get all current states.
+   * Get a flat traitName→state map. For multi-entity orbitals this
+   * returns one entry per trait collapsed onto the singleton scope (or
+   * the first observed scope if singleton is empty). Use
+   * `getAllStatesByScope()` to get the full per-entity view.
    */
   getAllStates() {
-    return new Map(this.states);
+    const out = /* @__PURE__ */ new Map();
+    for (const traitName of this.traits.keys()) {
+      const singleton = this.states.get(compositeKey(traitName, SINGLETON_SCOPE));
+      if (singleton) {
+        out.set(traitName, singleton);
+        continue;
+      }
+      for (const [key, state] of this.states) {
+        if (key.startsWith(`${traitName}::`)) {
+          out.set(traitName, state);
+          break;
+        }
+      }
+    }
+    return out;
+  }
+  /**
+   * Get every per-entity state row, grouped by trait. Useful for
+   * inspecting parallel subagent state.
+   */
+  getAllStatesByScope() {
+    const grouped = /* @__PURE__ */ new Map();
+    for (const [key, state] of this.states) {
+      const sep = key.indexOf("::");
+      if (sep < 0) continue;
+      const traitName = key.slice(0, sep);
+      const scope = key.slice(sep + 2);
+      let bucket = grouped.get(traitName);
+      if (!bucket) {
+        bucket = /* @__PURE__ */ new Map();
+        grouped.set(traitName, bucket);
+      }
+      bucket.set(scope, state);
+    }
+    return grouped;
   }
   /**
    * Check if a trait can handle an event from its current state.
    */
-  canHandleEvent(traitName, eventKey) {
+  canHandleEvent(traitName, eventKey, entityId) {
     const trait = this.traits.get(traitName);
-    const state = this.states.get(traitName);
+    const state = this.getOrInitState(traitName, entityId ?? SINGLETON_SCOPE);
     if (!trait || !state) return false;
     return !!findTransition(trait, state.currentState, normalizeEventKey(eventKey));
   }
@@ -468,9 +589,11 @@ var StateMachineManager = class {
    */
   sendEvent(eventKey, payload, entityData) {
     const results = [];
+    const scope = scopeOf(entityData);
     for (const [traitName, trait] of this.traits) {
-      const traitState = this.states.get(traitName);
+      const traitState = this.getOrInitState(traitName, scope);
       if (!traitState) continue;
+      const key = compositeKey(traitName, scope);
       const result = processEvent({
         traitState,
         trait,
@@ -482,7 +605,7 @@ var StateMachineManager = class {
         contextExtensions: this.config.contextExtensions
       });
       if (result.executed) {
-        this.states.set(traitName, {
+        this.states.set(key, {
           ...traitState,
           currentState: result.newState,
           previousState: result.previousState,
@@ -516,31 +639,29 @@ var StateMachineManager = class {
    * at a time per trait, effects fully awaited before the next event).
    */
   enqueueEvent(eventKey, payload, entityData) {
+    const scope = scopeOf(entityData);
     for (const [traitName] of this.traits) {
-      const queue = this.queues.get(traitName) ?? [];
+      const key = compositeKey(traitName, scope);
+      const queue = this.queues.get(key) ?? [];
       queue.push({ eventKey, payload, entityData });
-      this.queues.set(traitName, queue);
+      this.queues.set(key, queue);
     }
   }
   /**
-   * Drain a single trait's event queue, processing events sequentially.
-   *
-   * This is the core actor loop: each event is fully processed (including
-   * awaiting all effects) before the next event is dequeued. If the queue
-   * is already being drained for this trait, this call is a no-op (the
-   * running drain will pick up newly enqueued events).
-   *
-   * @param traitName - Which trait's queue to drain
-   * @param executeEffects - Async callback to run effects for a successful transition
+   * Drain a single (trait, entity) pair's event queue, processing
+   * events sequentially. Pass `entityId` to drain a specific entity
+   * instance; omit it to drain the singleton scope.
    */
-  async drainQueue(traitName, executeEffects) {
-    if (this.processing.has(traitName)) return;
-    this.processing.add(traitName);
-    const queue = this.queues.get(traitName) ?? [];
+  async drainQueue(traitName, executeEffects, entityId) {
+    const scope = entityId ?? SINGLETON_SCOPE;
+    const key = compositeKey(traitName, scope);
+    if (this.processing.has(key)) return;
+    this.processing.add(key);
+    const queue = this.queues.get(key) ?? [];
     while (queue.length > 0) {
       const entry = queue.shift();
       const trait = this.traits.get(traitName);
-      const traitState = this.states.get(traitName);
+      const traitState = this.getOrInitState(traitName, scope);
       if (!trait || !traitState) continue;
       const result = processEvent({
         traitState,
@@ -553,7 +674,7 @@ var StateMachineManager = class {
         contextExtensions: this.config.contextExtensions
       });
       if (result.executed) {
-        this.states.set(traitName, {
+        this.states.set(key, {
           ...traitState,
           currentState: result.newState,
           previousState: result.previousState,
@@ -573,35 +694,51 @@ var StateMachineManager = class {
         await executeEffects(traitName, result, entry.payload);
       }
     }
-    this.processing.delete(traitName);
+    this.processing.delete(key);
   }
   /**
    * Check whether a trait's queue is currently being drained.
    */
-  isProcessing(traitName) {
-    return this.processing.has(traitName);
+  isProcessing(traitName, entityId) {
+    return this.processing.has(compositeKey(traitName, entityId ?? SINGLETON_SCOPE));
   }
   /**
    * Get the number of pending events in a trait's queue.
    */
-  getQueueLength(traitName) {
-    return this.queues.get(traitName)?.length ?? 0;
+  getQueueLength(traitName, entityId) {
+    return this.queues.get(compositeKey(traitName, entityId ?? SINGLETON_SCOPE))?.length ?? 0;
   }
   /**
    * Reset a trait to its initial state.
+   *
+   * If `entityId` is provided, resets only that entity's scope.
+   * Otherwise resets every entity scope known for the trait.
    */
-  resetTrait(traitName) {
+  resetTrait(traitName, entityId) {
     const trait = this.traits.get(traitName);
-    if (trait) {
-      this.states.set(traitName, createInitialTraitState(trait));
+    if (!trait) return;
+    if (entityId) {
+      this.states.set(compositeKey(traitName, entityId), createInitialTraitState(trait));
+      return;
+    }
+    const prefix = `${traitName}::`;
+    for (const key of [...this.states.keys()]) {
+      if (key.startsWith(prefix)) {
+        this.states.set(key, createInitialTraitState(trait));
+      }
     }
   }
   /**
-   * Reset all traits to initial states.
+   * Reset all traits to initial states (every entity scope).
    */
   resetAll() {
     for (const [traitName, trait] of this.traits) {
-      this.states.set(traitName, createInitialTraitState(trait));
+      const prefix = `${traitName}::`;
+      for (const key of [...this.states.keys()]) {
+        if (key.startsWith(prefix)) {
+          this.states.set(key, createInitialTraitState(trait));
+        }
+      }
     }
   }
 };
@@ -2397,5 +2534,5 @@ function parseNamespacedEvent(eventName) {
 }
 
 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-GU35X5AW.js.map
-//# sourceMappingURL=chunk-GU35X5AW.js.map
+//# sourceMappingURL=chunk-QQIRPNHH.js.map
+//# sourceMappingURL=chunk-QQIRPNHH.js.map