@almadar/runtime 6.26.0 → 6.28.0

package/dist/{OrbitalServerRuntime-h0NCwFuc.d.ts → OrbitalServerRuntime-DCkk0alk.d.ts}

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { I as IEventBus, g as RuntimeEvent, f as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, i as TransitionObserver, C as ConfigContext, h as TraitState, j as TransitionResult, E as EvaluationContextExtensions, a as EffectHandlers } from './types-BA7GoDni.js';
-import { EventPayload, EntityRow, DeclaredTraitConfig, TraitConfig, Entity, OrbitalSchema, Orbital, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, TraitTick } from '@almadar/core';
+import { I as IEventBus, g as RuntimeEvent, f as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, i as TransitionObserver, C as ConfigContext, h as TraitState, j as TransitionResult, E as EvaluationContextExtensions, a as EffectHandlers } from './types-CguyGOms.js';
+import { EventPayload, EntityRow, ServiceCallResult, DeclaredTraitConfig, TraitConfig, Entity, OrbitalSchema, Orbital, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, TraitTick } from '@almadar/core';
 
 /**
  * EventBus - Platform-Agnostic Pub/Sub Implementation
@@ -308,6 +308,40 @@ declare class StateMachineManager {
     resetAll(): void;
 }
 
+/**
+ * Agent Substrate Handlers — Server-Side Only
+ *
+ * Provides implementations for the effect-position substrate operators:
+ * compose/compose-all, compose/compose-children, behavior/instantiate,
+ * behavior/call, validate/validate, lolo/emit-body.
+ *
+ * Used by OrbitalServerRuntime (interpreted path). Wired alongside
+ * createOsHandlers — same lazy-import + merge-under-user-handlers pattern.
+ *
+ * The actual service invocations are injected via the `services` field of
+ * AgentSubstrateHandlerContext. @almadar-io/rabit supplies these at runtime;
+ * tests can inject mocks. When a service is absent, the handler logs a
+ * warning and returns a safe default.
+ *
+ * NOT exported from the main index.ts because it references Node-only types.
+ * Import directly: import { createAgentSubstrateHandlers } from '@almadar/runtime/createAgentSubstrateHandlers';
+ *
+ * @packageDocumentation
+ */
+
+interface SubstrateServices {
+    composeAll?: (config: {
+        appName: string;
+        orbitals: unknown[];
+        layoutStrategy?: string;
+    }) => Promise<ServiceCallResult>;
+    composeChildren?: (parentName: string, children: unknown[]) => Promise<ServiceCallResult>;
+    instantiate?: (parentName: string, behavior: string, params?: unknown) => Promise<ServiceCallResult>;
+    call?: (behavior: string, method: string, params?: unknown) => Promise<ServiceCallResult>;
+    validate?: (orbitalName: string) => Promise<ServiceCallResult>;
+    emitBody?: (orbitalName: string, loloSource: string) => Promise<ServiceCallResult>;
+}
+
 /**
  * Pure config-default extraction — kept OUT of `OrbitalServerRuntime.ts` so the
  * package index can re-export it without dragging that module's node-only
@@ -993,6 +1027,12 @@ interface OrbitalServerRuntimeConfig {
      * The evaluator dispatches agent/* operators to ctx.agent.
      */
     contextExtensions?: EvaluationContextExtensions;
+    /**
+     * Substrate service implementations for effect-position operators
+     * (compose/compose-all, behavior/instantiate, validate/validate, etc.).
+     * @almadar-io/rabit injects these at runtime; tests can inject mocks.
+     */
+    substrateServices?: SubstrateServices;
 }
 
 declare class OrbitalServerRuntime {
@@ -1009,6 +1049,8 @@ declare class OrbitalServerRuntime {
     private eventNamespaceMap;
     private osHandlers;
     private osHandlersPromise;
+    private substrateHandlers;
+    private substrateHandlersPromise;
     private resolvedSchema;
     constructor(config?: OrbitalServerRuntimeConfig);
     /**
@@ -1020,6 +1062,12 @@ declare class OrbitalServerRuntime {
      * no-op in the browser (the import never runs behind the isNodeEnv guard).
      */
     private ensureOsHandlers;
+    /**
+     * Lazily wire the agent substrate effect handlers (compose/behavior/
+     * validate/lolo), merging them UNDER any user-provided handlers.
+     * Same deferred-import pattern as ensureOsHandlers.
+     */
+    private ensureAgentSubstrateHandlers;
     /**
      * Lazily construct a default loader when the caller didn't provide one
      * but `register()` needs to preprocess. Looks for `@almadar/std` in the

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { F as ClientEffectTuple, G as ClientNavigateTuple, H as ClientNotifyTuple, J as ClientRenderUITuple, K as EffectResult, e as InMemoryPersistence, M as LoaderConfig, O as OrbitalEventRequest, f as OrbitalEventResponse, N as OrbitalServerRuntime, g as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, Q as RuntimeTraitTick, p as collectDeclaredConfigDefaults, T as createOrbitalServerRuntime } from './OrbitalServerRuntime-h0NCwFuc.js';
-import './types-BA7GoDni.js';
+export { F as ClientEffectTuple, G as ClientNavigateTuple, H as ClientNotifyTuple, J as ClientRenderUITuple, K as EffectResult, e as InMemoryPersistence, M as LoaderConfig, O as OrbitalEventRequest, f as OrbitalEventResponse, N as OrbitalServerRuntime, g as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, Q as RuntimeTraitTick, p as collectDeclaredConfigDefaults, T as createOrbitalServerRuntime } from './OrbitalServerRuntime-DCkk0alk.js';
+import './types-CguyGOms.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,5 +1,5 @@
-import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-YNRDYK3N.js';
-export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-YNRDYK3N.js';
+import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-FWBY567U.js';
+export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-FWBY567U.js';
 import { isValidCronExpression } from './chunk-U4PL237A.js';
 import './chunk-PZ5AY32C.js';
 import { createLogger } from '@almadar/logger';
@@ -69,6 +69,8 @@ var OrbitalServerRuntime = class {
   eventNamespaceMap = {};
   osHandlers = null;
   osHandlersPromise = null;
+  substrateHandlers = null;
+  substrateHandlersPromise = null;
   resolvedSchema = null;
   constructor(config = {}) {
     this.config = {
@@ -127,6 +129,28 @@ var OrbitalServerRuntime = class {
     }
     return this.osHandlersPromise;
   }
+  /**
+   * Lazily wire the agent substrate effect handlers (compose/behavior/
+   * validate/lolo), merging them UNDER any user-provided handlers.
+   * Same deferred-import pattern as ensureOsHandlers.
+   */
+  async ensureAgentSubstrateHandlers() {
+    if (!isNodeEnv()) return;
+    if (!this.substrateHandlersPromise) {
+      this.substrateHandlersPromise = (async () => {
+        const { createAgentSubstrateHandlers } = await import('./createAgentSubstrateHandlers-4JMLGDZQ.js');
+        this.substrateHandlers = createAgentSubstrateHandlers({
+          emitEvent: (type, payload) => this.eventBus.emit(type, payload),
+          services: this.config.substrateServices ?? {}
+        });
+        this.config.effectHandlers = {
+          ...this.substrateHandlers.handlers,
+          ...this.config.effectHandlers
+        };
+      })();
+    }
+    return this.substrateHandlersPromise;
+  }
   /**
    * Lazily construct a default loader when the caller didn't provide one
    * but `register()` needs to preprocess. Looks for `@almadar/std` in the
@@ -749,6 +773,10 @@ var OrbitalServerRuntime = class {
       this.osHandlers.cleanup();
       this.osHandlers = null;
     }
+    if (this.substrateHandlers) {
+      this.substrateHandlers.cleanup();
+      this.substrateHandlers = null;
+    }
   }
   /**
    * Reset the mock persistence store to a clean-slate re-seed without
@@ -787,6 +815,7 @@ var OrbitalServerRuntime = class {
    */
   async processOrbitalEvent(orbitalName, request, onPush) {
     await this.ensureOsHandlers();
+    await this.ensureAgentSubstrateHandlers();
     const registered = this.orbitals.get(orbitalName);
     if (!registered) {
       return {