@almadar/runtime 2.5.0 → 2.6.0

package/dist/{OrbitalServerRuntime-Bel-jQ_o.d.ts → OrbitalServerRuntime-B-QeKtKd.d.ts}

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { I as IEventBus, i as RuntimeEvent, h as EventListener, U as Unsubscribe, E as EffectHandlers, g as Effect, T as TraitState } from './types-BrbvZxzX.js';
-import { OrbitalSchema, Orbital, Trait } from '@almadar/core';
+import { I as IEventBus, f as RuntimeEvent, e as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, h as TransitionObserver, g as TraitState, i as TransitionResult, d as Effect, E as EffectHandlers } from './types-DYcUvi4H.js';
+import { EventPayload, EntityRow, OrbitalSchema, Orbital, Trait } from '@almadar/core';
 
 /**
  * EventBus - Platform-Agnostic Pub/Sub Implementation
@@ -48,7 +48,7 @@ declare class EventBus implements IEventBus {
      * beyond `maxDepth`, the event is dropped and an error is logged.
      * This prevents infinite loops from circular emit/listen chains.
      */
-    emit(type: string, payload?: Record<string, unknown>, source?: RuntimeEvent['source']): void;
+    emit(type: string, payload?: EventPayload, source?: RuntimeEvent['source']): void;
     /**
      * Subscribe to an event type
      */
@@ -76,6 +76,168 @@ declare class EventBus implements IEventBus {
     getListenerCount(type: string): number;
 }
 
+/**
+ * StateMachineCore - Platform-Agnostic State Machine Logic
+ *
+ * Pure TypeScript implementation of trait state machine execution.
+ * Extracts the core logic from useTraitStateMachine for use on
+ * both client and server.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Find the initial state for a trait definition.
+ */
+declare function findInitialState(trait: TraitDefinition): string;
+/**
+ * Create initial trait state for a trait definition.
+ */
+declare function createInitialTraitState(trait: TraitDefinition): TraitState;
+/**
+ * Find a matching transition from the current state for the given event.
+ */
+declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string): TraitDefinition['transitions'][0] | undefined;
+/**
+ * Normalize event key - strip UI: prefix if present.
+ */
+declare function normalizeEventKey(eventKey: string): string;
+/**
+ * Options for processing an event through the state machine.
+ */
+interface ProcessEventOptions {
+    /** Current trait state */
+    traitState: TraitState;
+    /** Trait definition */
+    trait: TraitDefinition;
+    /** Event key to process */
+    eventKey: string;
+    /** Event payload */
+    payload?: EventPayload;
+    /** Entity data for binding resolution */
+    entityData?: EntityRow;
+    /**
+     * 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.
+ *
+ * This is a pure function that:
+ * 1. Finds matching transitions
+ * 2. Evaluates guards
+ * 3. Returns the transition result (but does not execute effects)
+ *
+ * @returns TransitionResult with effects to execute
+ *
+ * @example
+ * ```ts
+ * const result = processEvent({
+ *   traitState: { traitName: 'Cart', currentState: 'empty', ... },
+ *   trait: cartTraitDefinition,
+ *   eventKey: 'ADD_ITEM',
+ *   payload: { productId: '123' },
+ * });
+ *
+ * if (result.executed) {
+ *   // Execute effects
+ *   for (const effect of result.effects) {
+ *     effectExecutor.execute(effect);
+ *   }
+ *   // Update state
+ *   traitState.currentState = result.newState;
+ * }
+ * ```
+ */
+declare function processEvent(options: ProcessEventOptions): TransitionResult;
+declare class StateMachineManager {
+    private traits;
+    private states;
+    private config;
+    private observer?;
+    private queues;
+    private processing;
+    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.
+     */
+    addTrait(trait: TraitDefinition): void;
+    /**
+     * Remove a trait from the manager.
+     */
+    removeTrait(traitName: string): void;
+    /**
+     * Get current state for a trait.
+     */
+    getState(traitName: string): TraitState | undefined;
+    /**
+     * Get all current states.
+     */
+    getAllStates(): Map<string, TraitState>;
+    /**
+     * Check if a trait can handle an event from its current state.
+     */
+    canHandleEvent(traitName: string, eventKey: string): boolean;
+    /**
+     * Send an event to all traits.
+     *
+     * @returns Array of transition results (one per trait that had a matching transition)
+     */
+    sendEvent(eventKey: string, payload?: EventPayload, entityData?: EntityRow): Array<{
+        traitName: string;
+        result: TransitionResult;
+    }>;
+    /**
+     * Enqueue an event into every trait's per-trait queue.
+     *
+     * Events are not processed immediately. Call `drainQueue()` for each
+     * trait to process them sequentially (actor-model guarantee: one event
+     * at a time per trait, effects fully awaited before the next event).
+     */
+    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
+     */
+    drainQueue(traitName: string, executeEffects: (traitName: string, result: TransitionResult, payload?: EventPayload) => Promise<void>): Promise<void>;
+    /**
+     * Check whether a trait's queue is currently being drained.
+     */
+    isProcessing(traitName: string): boolean;
+    /**
+     * Get the number of pending events in a trait's queue.
+     */
+    getQueueLength(traitName: string): number;
+    /**
+     * Reset a trait to its initial state.
+     */
+    resetTrait(traitName: string): void;
+    /**
+     * Reset all traits to initial states.
+     */
+    resetAll(): void;
+}
+
 /**
  * External Orbital Loader
  *
@@ -436,7 +598,7 @@ interface RuntimeOrbital {
             };
         }>;
         /** Pre-defined entity instances to seed on registration */
-        instances?: Array<Record<string, unknown>>;
+        instances?: Array<EntityRow>;
     };
     traits: RuntimeTrait[];
 }
@@ -471,18 +633,26 @@ interface RuntimeTrait {
     listens?: Array<{
         event: string;
         triggers: string;
-        payloadMapping?: Record<string, unknown>;
+        payloadMapping?: EventPayload;
     }>;
     emits?: string[];
     /** Scheduled ticks for this trait */
     ticks?: RuntimeTraitTick[];
 }
+/**
+ * Registered orbital with runtime state
+ */
+interface RegisteredOrbital {
+    schema: RuntimeOrbital;
+    manager: StateMachineManager;
+    entityData: Map<string, EntityRow>;
+}
 /**
  * Event sent from client to server
  */
 interface OrbitalEventRequest {
     event: string;
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     entityId?: string;
     /** User context for @user bindings (from Firebase auth) */
     user?: {
@@ -504,7 +674,9 @@ interface OrbitalEventResponse {
         payload?: unknown;
     }>;
     /** Entity data fetched by `fetch` effects - keyed by entity type */
-    data?: Record<string, Record<string, unknown> | Record<string, unknown>[]>;
+    data?: {
+        [entityType: string]: EntityRow | EntityRow[];
+    };
     /** Client-side effects to execute (render-ui, navigate, notify) */
     clientEffects?: Array<unknown>;
     /** Results from server-side effects (persist, call-service, set) */
@@ -523,7 +695,7 @@ interface EffectResult {
     /** Entity type affected (for persist/set/ref/deref/swap) */
     entityType?: string;
     /** Result data from the effect */
-    data?: Record<string, unknown>;
+    data?: EntityRow;
     /** Whether the effect succeeded */
     success: boolean;
     /** Error message if failed */
@@ -583,16 +755,16 @@ interface OrbitalServerRuntimeConfig {
  * Adapter for persisting entity data
  */
 interface PersistenceAdapter {
-    create(entityType: string, data: Record<string, unknown>): Promise<{
+    create(entityType: string, data: EntityRow): Promise<{
         id: string;
     }>;
-    update(entityType: string, id: string, data: Record<string, unknown>): Promise<void>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
     delete(entityType: string, id: string): Promise<void>;
-    getById(entityType: string, id: string): Promise<Record<string, unknown> | null>;
-    list(entityType: string): Promise<Array<Record<string, unknown>>>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<Array<EntityRow>>;
 }
 declare class OrbitalServerRuntime {
-    private orbitals;
+    protected orbitals: Map<string, RegisteredOrbital>;
     private eventBus;
     private config;
     private persistence;
@@ -782,4 +954,4 @@ declare class OrbitalServerRuntime {
  */
 declare function createOrbitalServerRuntime(config?: OrbitalServerRuntimeConfig): OrbitalServerRuntime;
 
-export { type EntitySharingMap as E, type LoaderConfig as L, type OrbitalEventRequest as O, type PersistenceAdapter as P, type RuntimeOrbital as R, EventBus as a, type EventNamespaceMap as b, type OrbitalEventResponse as c, type OrbitalServerRuntimeConfig as d, type PreprocessOptions as e, type PreprocessResult as f, type PreprocessedSchema as g, type RuntimeOrbitalSchema as h, type RuntimeTrait as i, getIsolatedCollectionName as j, getNamespacedEvent as k, isNamespacedEvent as l, preprocessSchema as m, type EffectResult as n, OrbitalServerRuntime as o, parseNamespacedEvent as p, type RuntimeTraitTick as q, createOrbitalServerRuntime as r };
+export { type EntitySharingMap as E, type LoaderConfig as L, type OrbitalEventRequest as O, type PersistenceAdapter as P, type RegisteredOrbital as R, StateMachineManager as S, EventBus as a, type EventNamespaceMap as b, type OrbitalEventResponse as c, type OrbitalServerRuntimeConfig as d, type PreprocessOptions as e, type PreprocessResult as f, type PreprocessedSchema as g, type ProcessEventOptions as h, type RuntimeOrbital as i, type RuntimeOrbitalSchema as j, type RuntimeTrait as k, createInitialTraitState as l, findInitialState as m, findTransition as n, getIsolatedCollectionName as o, getNamespacedEvent as p, isNamespacedEvent as q, normalizeEventKey as r, parseNamespacedEvent as s, preprocessSchema as t, processEvent as u, type EffectResult as v, OrbitalServerRuntime as w, type RuntimeTraitTick as x, createOrbitalServerRuntime as y };

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { n as EffectResult, L as LoaderConfig, O as OrbitalEventRequest, c as OrbitalEventResponse, o as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, q as RuntimeTraitTick, r as createOrbitalServerRuntime } from './OrbitalServerRuntime-Bel-jQ_o.js';
-import './types-BrbvZxzX.js';
+export { v as EffectResult, L as LoaderConfig, O as OrbitalEventRequest, c as OrbitalEventResponse, w as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, x as RuntimeTraitTick, y as createOrbitalServerRuntime } from './OrbitalServerRuntime-B-QeKtKd.js';
+import './types-DYcUvi4H.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,4 +1,4 @@
-import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-ICTFAD3I.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-ESNML4B4.js';
 import { Router } from 'express';
 import { evaluateGuard, evaluate } from '@almadar/evaluator';
 import { faker } from '@faker-js/faker';
@@ -146,8 +146,9 @@ var MockPersistenceAdapter = class {
         return null;
       // Relations need special handling
       case "array":
+        return [];
       case "object":
-        return field.type === "array" ? [] : {};
+        return null;
       default:
         return this.generateStringValue(entityName, field, index);
     }
@@ -1727,15 +1728,17 @@ var OrbitalServerRuntime = class {
       const populatedFieldName = includeField.endsWith("Id") ? includeField.slice(0, -2) : includeField;
       for (const entity of entities) {
         const fkValue = entity[foreignKeyField];
+        const entityRecord = entity;
         if (cardinality === "one" || cardinality === "many-to-one") {
           if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
-            entity[populatedFieldName] = relatedEntities.get(fkValue);
+            entityRecord[populatedFieldName] = relatedEntities.get(fkValue);
           }
         } else {
           if (Array.isArray(fkValue)) {
-            entity[populatedFieldName] = fkValue.filter((id) => typeof id === "string").map((id) => relatedEntities.get(id)).filter(Boolean);
+            const fkIds = fkValue.filter((id) => typeof id === "string");
+            entityRecord[populatedFieldName] = fkIds.map((id) => relatedEntities.get(id)).filter(Boolean);
           } else if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
-            entity[populatedFieldName] = [relatedEntities.get(fkValue)];
+            entityRecord[populatedFieldName] = [relatedEntities.get(fkValue)];
           }
         }
       }
@@ -1802,10 +1805,8 @@ var OrbitalServerRuntime = class {
           const orbitalName = req.params.orbital;
           const firebaseUser = req.firebaseUser;
           const user = firebaseUser ? {
-            uid: firebaseUser.uid,
-            email: firebaseUser.email,
-            displayName: firebaseUser.name,
-            ...firebaseUser
+            ...firebaseUser,
+            displayName: firebaseUser.name ?? firebaseUser.displayName
           } : void 0;
           const result = await this.processOrbitalEvent(orbitalName, {
             ...req.body,