@almadar/runtime 3.1.0 → 3.1.2

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

@@ -164,6 +164,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 +197,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 +244,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-DrZB9ksb.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-HIM4HJAN.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-KCXJNXQZ.js';
 import './chunk-PZ5AY32C.js';
 import { Router } from 'express';
 import * as fs from 'fs';
@@ -943,7 +943,10 @@ var OrbitalServerRuntime = class {
                 }
               }
             }
-            const forwardedEntityId = event.payload?.entityId ?? event.payload?.orbitalName;
+            const raw = event.payload;
+            const mapped = mappedPayload;
+            const pickId = (field) => mapped?.[field] ?? raw?.[field];
+            const forwardedEntityId = pickId("entityId") ?? pickId("orbitalName");
             await this.processOrbitalEvent(orbitalName, {
               event: listener.triggers,
               payload: mappedPayload,