@almadar/runtime 1.0.0

package/dist/OrbitalServerRuntime-COj7K1yM.d.ts

@@ -0,0 +1,736 @@
+import { Router } from 'express';
+import { I as IEventBus, R as RuntimeEvent, e as EventListener, U as Unsubscribe, E as EffectHandlers, d as Effect, T as TraitState } from './types-JFCKD0FU.js';
+import { OrbitalSchema, Orbital, Trait } from '@almadar/core';
+
+/**
+ * EventBus - Platform-Agnostic Pub/Sub Implementation
+ *
+ * Pure TypeScript event bus for cross-trait communication.
+ * Works on both client (browser) and server (Node.js).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * EventBus - Simple pub/sub event bus
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus({ debug: true });
+ *
+ * // Subscribe
+ * const unsub = bus.on('ORDER_CONFIRMED', (event) => {
+ *   console.log('Order confirmed:', event.payload);
+ * });
+ *
+ * // Emit
+ * bus.emit('ORDER_CONFIRMED', { orderId: '123' });
+ *
+ * // Unsubscribe
+ * unsub();
+ * ```
+ */
+declare class EventBus implements IEventBus {
+    private listeners;
+    private debug;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Emit an event to all registered listeners
+     */
+    emit(type: string, payload?: Record<string, unknown>, source?: RuntimeEvent['source']): void;
+    /**
+     * Subscribe to an event type
+     */
+    on(type: string, listener: EventListener): Unsubscribe;
+    /**
+     * Subscribe to ALL events (wildcard listener)
+     * Useful for event tracking, logging, debugging
+     */
+    onAny(listener: EventListener): Unsubscribe;
+    /**
+     * Check if there are listeners for an event type
+     */
+    hasListeners(type: string): boolean;
+    /**
+     * Get all registered event types
+     */
+    getRegisteredEvents(): string[];
+    /**
+     * Clear all listeners
+     */
+    clear(): void;
+    /**
+     * Get listener count for an event type (for testing)
+     */
+    getListenerCount(type: string): number;
+}
+
+/**
+ * External Orbital Loader
+ *
+ * Loads external .orb files from various sources:
+ * - Local filesystem (relative paths)
+ * - Standard library (std/...)
+ * - Scoped packages (@name/...)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Loader options.
+ */
+interface LoaderOptions {
+    /** Base directory for resolving relative imports */
+    basePath: string;
+    /** Standard library root path */
+    stdLibPath?: string;
+    /** Scoped package roots (e.g., { "@game-lib": "/path/to/lib" }) */
+    scopedPaths?: Record<string, string>;
+    /** Whether to allow paths outside basePath (security) */
+    allowOutsideBasePath?: boolean;
+}
+
+/**
+ * SchemaLoader Interface
+ *
+ * Abstract interface for loading OrbitalSchema files from various sources.
+ * Implementations exist for:
+ * - FileSystemLoader (Node.js) - uses fs module
+ * - HttpLoader (Browser) - uses fetch API
+ * - UnifiedLoader (Auto-detect) - routes to appropriate loader
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result of loading a schema.
+ */
+interface LoadedSchema {
+    /** The loaded schema */
+    schema: OrbitalSchema;
+    /** Source path/URL (resolved) */
+    sourcePath: string;
+    /** Original import path */
+    importPath: string;
+}
+/**
+ * Result of loading a single orbital from a schema.
+ */
+interface LoadedOrbital {
+    /** The loaded orbital */
+    orbital: Orbital;
+    /** Source path/URL (resolved) */
+    sourcePath: string;
+    /** Original import path */
+    importPath: string;
+}
+/**
+ * Loader result with error handling.
+ */
+type LoadResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Abstract interface for schema loaders.
+ *
+ * All loaders must implement:
+ * - load() - Load a schema from an import path
+ * - resolvePath() - Resolve an import path to absolute path/URL
+ *
+ * @example
+ * ```typescript
+ * // Using FileSystemLoader (Node.js)
+ * const loader: SchemaLoader = new FileSystemLoader({ basePath: "/schemas" });
+ * const result = await loader.load("./my-schema.orb");
+ *
+ * // Using HttpLoader (Browser)
+ * const loader: SchemaLoader = new HttpLoader({ basePath: "/api/schemas" });
+ * const result = await loader.load("./my-schema.orb");
+ *
+ * // Using UnifiedLoader (auto-detect)
+ * const loader: SchemaLoader = createUnifiedLoader({ basePath: "/schemas" });
+ * const result = await loader.load("./my-schema.orb");
+ * ```
+ */
+interface SchemaLoader {
+    /**
+     * Load a schema from an import path.
+     *
+     * @param importPath - The import path (e.g., "./health.orb", "std/behaviors/game-core")
+     * @param fromPath - The path of the file doing the import (for relative resolution)
+     * @param chain - Import chain for circular detection (optional)
+     */
+    load(importPath: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedSchema>>;
+    /**
+     * Load a specific orbital from a schema by name.
+     *
+     * @param importPath - The import path
+     * @param orbitalName - The orbital name (optional, defaults to first orbital)
+     * @param fromPath - The path of the file doing the import
+     * @param chain - Import chain for circular detection (optional)
+     */
+    loadOrbital(importPath: string, orbitalName?: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedOrbital>>;
+    /**
+     * Resolve an import path to an absolute path/URL.
+     *
+     * @param importPath - The import path
+     * @param fromPath - The path of the file doing the import (optional)
+     */
+    resolvePath(importPath: string, fromPath?: string): LoadResult<string>;
+    /**
+     * Clear the loader's cache.
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+    };
+}
+/**
+ * Interface for import chain (circular detection).
+ * This allows different implementations to interoperate.
+ */
+interface ImportChainLike {
+    /**
+     * Try to add a path to the chain.
+     * @returns Error message if circular, null if OK
+     */
+    push(absolutePath: string): string | null;
+    /**
+     * Remove the last path from the chain.
+     */
+    pop(): void;
+    /**
+     * Clone the chain for nested loading.
+     */
+    clone(): ImportChainLike;
+}
+
+/**
+ * Reference Resolver
+ *
+ * Resolves `uses` imports and component references in OrbitalSchema.
+ * Handles:
+ * - `Alias.entity` entity references
+ * - `Alias.traits.TraitName` trait references
+ * - `Alias.pages.PageName` page references
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Resolution options.
+ */
+interface ResolveOptions extends LoaderOptions {
+    /** Map of local trait definitions (name -> trait) */
+    localTraits?: Map<string, Trait>;
+    /** Whether to skip loading external imports (for testing) */
+    skipExternalLoading?: boolean;
+    /** Custom schema loader instance (optional, defaults to ExternalOrbitalLoader) */
+    loader?: SchemaLoader;
+}
+
+/**
+ * Uses Integration for OrbitalServerRuntime
+ *
+ * Pre-processes OrbitalSchema to resolve `uses` declarations
+ * before registration with the runtime.
+ *
+ * Features:
+ * - Resolves all `uses` imports
+ * - Expands entity/trait/page references
+ * - Handles entity persistence semantics
+ * - Applies event namespacing for imported traits
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result of pre-processing a schema.
+ */
+interface PreprocessedSchema {
+    /** Schema with all references resolved */
+    schema: OrbitalSchema;
+    /** Entity sharing information (for runtime isolation) */
+    entitySharing: EntitySharingMap;
+    /** Event namespace mapping */
+    eventNamespaces: EventNamespaceMap;
+    /** Warnings from resolution */
+    warnings: string[];
+}
+/**
+ * Map of orbital -> entity sharing info
+ */
+interface EntitySharingMap {
+    [orbitalName: string]: {
+        /** The entity name */
+        entityName: string;
+        /** Persistence type */
+        persistence: "persistent" | "runtime" | "singleton";
+        /** Whether this entity is shared with other orbitals */
+        isShared: boolean;
+        /** Source orbital if imported */
+        sourceAlias?: string;
+        /** Collection name for persistent entities */
+        collectionName?: string;
+    };
+}
+/**
+ * Map of trait events to namespaced events
+ */
+interface EventNamespaceMap {
+    [orbitalName: string]: {
+        [traitName: string]: {
+            /** Original event -> namespaced event */
+            emits: Record<string, string>;
+            /** Namespaced event -> original event (for listeners) */
+            listens: Record<string, string>;
+        };
+    };
+}
+/**
+ * Options for preprocessing.
+ */
+interface PreprocessOptions extends ResolveOptions {
+    /** Apply event namespacing to imported traits */
+    namespaceEvents?: boolean;
+}
+/**
+ * Result type for preprocessing.
+ */
+type PreprocessResult = {
+    success: true;
+    data: PreprocessedSchema;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * Preprocess a schema to resolve all `uses` references.
+ *
+ * This is the integration point between the new `uses` system and the
+ * existing OrbitalServerRuntime. It:
+ *
+ * 1. Resolves all `uses` declarations
+ * 2. Expands entity references to inline definitions
+ * 3. Expands trait references to inline definitions
+ * 4. Expands page references with path overrides
+ * 5. Builds entity sharing map for runtime isolation
+ * 6. Builds event namespace map for cross-orbital events
+ *
+ * @example
+ * ```typescript
+ * const result = await preprocessSchema(schema, {
+ *   basePath: "/project/schemas",
+ * });
+ *
+ * if (result.success) {
+ *   // Register the preprocessed schema
+ *   runtime.register(result.data.schema);
+ *
+ *   // Use entitySharing for isolation decisions
+ *   if (result.data.entitySharing["Level1"].persistence === "runtime") {
+ *     // Entities are isolated per orbital
+ *   }
+ * }
+ * ```
+ */
+declare function preprocessSchema(schema: OrbitalSchema, options: PreprocessOptions): Promise<PreprocessResult>;
+/**
+ * Get the collection name for an orbital's entity, considering isolation.
+ *
+ * - `persistent` entities share the same collection
+ * - `runtime` entities get isolated collections per orbital
+ * - `singleton` entities share a single-record collection
+ */
+declare function getIsolatedCollectionName(orbitalName: string, entitySharing: EntitySharingMap): string;
+/**
+ * Get the namespaced event name for an orbital's trait event.
+ */
+declare function getNamespacedEvent(orbitalName: string, traitName: string, eventName: string, eventNamespaces: EventNamespaceMap): string;
+/**
+ * Check if an event name is namespaced (contains dots).
+ */
+declare function isNamespacedEvent(eventName: string): boolean;
+/**
+ * Parse a namespaced event name.
+ */
+declare function parseNamespacedEvent(eventName: string): {
+    orbital?: string;
+    trait?: string;
+    event: string;
+};
+
+/**
+ * OrbitalServerRuntime - Dynamic Server-Side Orbital Execution
+ *
+ * This runtime takes an OrbitalSchema and dynamically:
+ * 1. Registers all orbitals and their traits
+ * 2. Creates Express routes for trait communication
+ * 3. Executes state machines server-side
+ * 4. Handles cross-orbital event propagation
+ *
+ * This is the "interpreted" mode - no compilation needed.
+ * The compiler generates equivalent static code for production.
+ *
+ * @example
+ * ```typescript
+ * import { OrbitalServerRuntime } from '@kflow-builder/shared/runtime';
+ * import express from 'express';
+ *
+ * const app = express();
+ * const runtime = new OrbitalServerRuntime();
+ *
+ * // Register schema (can be loaded from file, API, etc.)
+ * runtime.register(orbitalSchema);
+ *
+ * // Mount orbital routes
+ * app.use('/api/orbitals', runtime.router());
+ *
+ * // Client can now:
+ * // POST /api/orbitals/:orbital/events  - Send event to orbital
+ * // GET  /api/orbitals/:orbital/state   - Get current state
+ * // GET  /api/orbitals                  - List registered orbitals
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Simplified OrbitalSchema for runtime registration
+ * (Subset of full OrbitalSchema - just what's needed for execution)
+ */
+interface RuntimeOrbitalSchema {
+    name: string;
+    version?: string;
+    orbitals: RuntimeOrbital[];
+}
+interface RuntimeOrbital {
+    name: string;
+    entity: {
+        name: string;
+        fields?: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+    traits: RuntimeTrait[];
+}
+/**
+ * Tick definition for scheduled effects
+ */
+interface RuntimeTraitTick {
+    /** Unique name for this tick */
+    name: string;
+    /** Interval in milliseconds, or cron expression string */
+    interval: number | string;
+    /** Guard condition (S-expression) - tick only executes if guard passes */
+    guard?: unknown;
+    /** Effects to execute when tick fires */
+    effects: Effect[];
+    /** Filter to specific entity IDs (optional) */
+    appliesTo?: string[];
+}
+interface RuntimeTrait {
+    name: string;
+    states: Array<{
+        name: string;
+        isInitial?: boolean;
+    }>;
+    transitions: Array<{
+        from: string;
+        to: string;
+        event: string;
+        guard?: unknown;
+        effects?: Effect[];
+    }>;
+    listens?: Array<{
+        event: string;
+        triggers: string;
+        payloadMapping?: Record<string, unknown>;
+    }>;
+    emits?: string[];
+    /** Scheduled ticks for this trait */
+    ticks?: RuntimeTraitTick[];
+}
+/**
+ * Event sent from client to server
+ */
+interface OrbitalEventRequest {
+    event: string;
+    payload?: Record<string, unknown>;
+    entityId?: string;
+    /** User context for @user bindings (from Firebase auth) */
+    user?: {
+        uid: string;
+        email?: string;
+        displayName?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Response from event processing
+ */
+interface OrbitalEventResponse {
+    success: boolean;
+    transitioned: boolean;
+    states: Record<string, string>;
+    emittedEvents: Array<{
+        event: string;
+        payload?: unknown;
+    }>;
+    /** Entity data fetched by `fetch` effects - keyed by entity type */
+    data?: Record<string, Record<string, unknown> | Record<string, unknown>[]>;
+    /** Client-side effects to execute (render-ui, navigate, notify) */
+    clientEffects?: Array<unknown>;
+    /** Results from server-side effects (persist, call-service, set) */
+    effectResults?: EffectResult[];
+    error?: string;
+}
+/**
+ * Result of a server-side effect execution.
+ * Closes the circuit by returning effect outcomes to the client.
+ */
+interface EffectResult {
+    /** Effect type that was executed */
+    effect: 'persist' | 'call-service' | 'set';
+    /** Action performed (e.g., 'create', 'update', 'delete' for persist) */
+    action?: string;
+    /** Entity type affected (for persist/set) */
+    entityType?: string;
+    /** Result data from the effect */
+    data?: Record<string, unknown>;
+    /** Whether the effect succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Loader configuration for resolving `uses` imports
+ */
+interface LoaderConfig {
+    /** Base path for schema files */
+    basePath: string;
+    /** Standard library path (filesystem or URL) */
+    stdLibPath?: string;
+    /** Scoped package paths */
+    scopedPaths?: Record<string, string>;
+    /** Custom loader instance (overrides basePath/stdLibPath) */
+    loader?: SchemaLoader;
+}
+/**
+ * Runtime configuration
+ */
+interface OrbitalServerRuntimeConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom effect handlers (for integrating with your data layer) */
+    effectHandlers?: Partial<EffectHandlers>;
+    /** Persistence adapter for entity data */
+    persistence?: PersistenceAdapter;
+    /**
+     * Data mode:
+     * - 'mock': Use faker-generated mock data (default for preview)
+     * - 'real': Use actual persistence layer
+     */
+    mode?: 'mock' | 'real';
+    /** Seed for deterministic mock data generation */
+    mockSeed?: number;
+    /** Number of mock records to generate per entity */
+    mockSeedCount?: number;
+    /**
+     * Loader configuration for resolving `uses` imports.
+     * Required when using `registerWithPreprocess` or `autoPreprocess`.
+     */
+    loaderConfig?: LoaderConfig;
+    /**
+     * Automatically preprocess schemas on register() to resolve `uses` imports.
+     * Requires `loaderConfig` to be set.
+     * Default: false
+     */
+    autoPreprocess?: boolean;
+    /**
+     * Apply event namespacing to imported traits.
+     * Default: true
+     */
+    namespaceEvents?: boolean;
+}
+/**
+ * Adapter for persisting entity data
+ */
+interface PersistenceAdapter {
+    create(entityType: string, data: Record<string, unknown>): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: Record<string, unknown>): 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>>>;
+}
+declare class OrbitalServerRuntime {
+    private orbitals;
+    private eventBus;
+    private config;
+    private persistence;
+    private listenerCleanups;
+    private tickBindings;
+    private loader;
+    private preprocessedCache;
+    private entitySharingMap;
+    private eventNamespaceMap;
+    constructor(config?: OrbitalServerRuntimeConfig);
+    /**
+     * Register an OrbitalSchema for execution.
+     *
+     * If `autoPreprocess` is enabled in config and schema has `uses` declarations,
+     * it will be preprocessed first to resolve imports.
+     *
+     * For explicit preprocessing control, use `registerWithPreprocess()`.
+     */
+    register(schema: RuntimeOrbitalSchema): void;
+    /**
+     * Register an OrbitalSchema with preprocessing to resolve `uses` imports.
+     *
+     * This method:
+     * 1. Loads all external orbitals referenced in `uses` declarations
+     * 2. Expands entity/trait/page references to inline definitions
+     * 3. Builds entity sharing and event namespace maps
+     * 4. Caches the preprocessed result
+     * 5. Registers the resolved schema
+     *
+     * @param schema - Schema with potential `uses` declarations
+     * @param options - Optional preprocessing options
+     * @returns Preprocessing result with entity sharing info
+     *
+     * @example
+     * ```typescript
+     * const runtime = new OrbitalServerRuntime({
+     *   loaderConfig: {
+     *     basePath: '/schemas',
+     *     stdLibPath: '/std',
+     *   },
+     * });
+     *
+     * const result = await runtime.registerWithPreprocess(schema);
+     * if (result.success) {
+     *   console.log('Registered with', Object.keys(result.entitySharing).length, 'orbitals');
+     * }
+     * ```
+     */
+    registerWithPreprocess(schema: RuntimeOrbitalSchema, options?: {
+        sourcePath?: string;
+    }): Promise<{
+        success: boolean;
+        entitySharing?: EntitySharingMap;
+        eventNamespaces?: EventNamespaceMap;
+        warnings?: string[];
+        errors?: string[];
+    }>;
+    /**
+     * Get entity sharing information for registered orbitals.
+     * Useful for determining entity isolation and collection names.
+     */
+    getEntitySharing(): EntitySharingMap;
+    /**
+     * Get event namespace mapping for registered orbitals.
+     * Useful for debugging cross-orbital event routing.
+     */
+    getEventNamespaces(): EventNamespaceMap;
+    /**
+     * Clear the preprocessing cache.
+     */
+    clearPreprocessCache(): void;
+    /**
+     * Register a single orbital
+     */
+    private registerOrbital;
+    /**
+     * Set up event listeners for cross-orbital communication
+     */
+    private setupEventListeners;
+    /**
+     * Set up scheduled ticks for all traits
+     */
+    private setupTicks;
+    /**
+     * Register a single tick
+     */
+    private registerTick;
+    /**
+     * Parse interval string to milliseconds
+     * Supports: '5s', '1m', '1h', '30000' (ms)
+     */
+    private parseIntervalString;
+    /**
+     * Execute a tick for all applicable entities
+     */
+    private executeTick;
+    /**
+     * Clean up all active ticks
+     */
+    private cleanupTicks;
+    /**
+     * Unregister all orbitals and clean up
+     */
+    unregisterAll(): void;
+    /**
+     * Process an event for an orbital
+     */
+    processOrbitalEvent(orbitalName: string, request: OrbitalEventRequest): Promise<OrbitalEventResponse>;
+    /**
+     * Execute effects from a transition
+     */
+    private executeEffects;
+    /**
+     * Create Express router for orbital API endpoints
+     *
+     * All data access goes through trait events with guards.
+     * No direct CRUD routes - use events with `fetch` effects.
+     *
+     * Routes:
+     * - GET  /              - List registered orbitals
+     * - GET  /:orbital      - Get orbital info and current states
+     * - POST /:orbital/events - Send event to orbital (includes data from `fetch` effects)
+     */
+    router(): Router;
+    /**
+     * Get the event bus for manual event emission
+     */
+    getEventBus(): EventBus;
+    /**
+     * Get state for a specific orbital/trait
+     */
+    getState(orbitalName: string, traitName?: string): TraitState | Record<string, TraitState> | undefined;
+    /**
+     * List registered orbitals
+     */
+    listOrbitals(): string[];
+    /**
+     * Check if an orbital is registered
+     */
+    hasOrbital(name: string): boolean;
+    /**
+     * Get information about active ticks
+     */
+    getActiveTicks(): Array<{
+        orbital: string;
+        trait: string;
+        tick: string;
+        interval: number | string;
+        hasGuard: boolean;
+    }>;
+}
+/**
+ * Factory function to create a runtime instance
+ */
+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 };