@almadar/runtime 6.32.0 → 6.34.0

package/dist/OrbitalServerRuntime.js

@@ -1,12 +1,37 @@
-import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-YFH577FH.js';
-export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-YFH577FH.js';
+import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, resolveCallSitePayloadCaptures, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-TRA44DDY.js';
+export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-TRA44DDY.js';
 import { isValidCronExpression } from './chunk-OU3ITB5S.js';
+import './chunk-OQJIK6PZ.js';
+import './chunk-SCRAHWOC.js';
 import './chunk-MLKGABMK.js';
 import { createLogger } from '@almadar/logger';
 import * as nodeModule from 'module';
 import { evaluateGuard, evaluate } from '@almadar/evaluator';
-import { isInlineTrait, isEntityCall } from '@almadar/core';
+import { buildResolvedTraitConfigs, isInlineTrait, isEntityCall } from '@almadar/core';
 
+// src/identity/routing.ts
+function eventRouteKey(eventName, eventId) {
+  return eventId ? `@evt:${eventId}` : eventName;
+}
+function buildSourceMatcher(src, listenerOrbital) {
+  if (src.kind === "any") return () => true;
+  if (src.kind === "trait") {
+    if (src.traitId !== void 0) {
+      const wantedTraitId = src.traitId;
+      return (source) => !!source && source.traitId === wantedTraitId;
+    }
+    const wantedTrait2 = src.trait;
+    return (source) => !!source && source.orbital === listenerOrbital && source.trait === wantedTrait2;
+  }
+  if (src.orbitalId !== void 0 && src.traitId !== void 0) {
+    const wantedOrbitalId = src.orbitalId;
+    const wantedTraitId = src.traitId;
+    return (source) => !!source && source.orbitalId === wantedOrbitalId && source.traitId === wantedTraitId;
+  }
+  const wantedOrbital = src.orbital;
+  const wantedTrait = src.trait;
+  return (source) => !!source && source.orbital === wantedOrbital && source.trait === wantedTrait;
+}
 var _resolvedNodeRequire = null;
 function nodeRequire(modulePath) {
   if (!_resolvedNodeRequire) {
@@ -72,6 +97,16 @@ var OrbitalServerRuntime = class {
   substrateHandlers = null;
   substrateHandlersPromise = null;
   resolvedSchema = null;
+  /**
+   * Trait name -> resolved `TraitConfig`, computed once per `register()` via
+   * `buildResolvedTraitConfigs` (`@almadar/core`). An embedded sub-trait's
+   * OWN declared config schema (`registered.traits` / `collectDeclaredConfigDefaults`)
+   * carries `@config.X` forwards verbatim — this map chains those through to
+   * the trait that actually embeds it (see `embedded-trait-config.ts` for the
+   * full rationale). Used as a fallback layer in `buildBindingContext` behind
+   * `declaredDefaults` and ahead of `callSiteOverride`.
+   */
+  resolvedTraitConfigs = {};
   constructor(config = {}) {
     this.config = {
       mode: "mock",
@@ -257,6 +292,7 @@ var OrbitalServerRuntime = class {
     this.setupEventListeners();
     this.setupTicks();
     this.resolvedSchema = schema;
+    this.resolvedTraitConfigs = buildResolvedTraitConfigs(schema);
   }
   /**
    * Register an OrbitalSchema synchronously (for backward compatibility).
@@ -273,6 +309,7 @@ var OrbitalServerRuntime = class {
     this.setupEventListeners();
     this.setupTicks();
     this.resolvedSchema = schema;
+    this.resolvedTraitConfigs = buildResolvedTraitConfigs(schema);
   }
   /**
    * Returns the schema that this runtime is currently executing, post-
@@ -440,6 +477,9 @@ var OrbitalServerRuntime = class {
       const states = sm?.states || [];
       const transitions = sm?.transitions || [];
       return {
+        // V4 dual-carry: thread the trait id so the manager's id index is
+        // populated for ledger-backed schemas (undefined → name-keyed only).
+        ...t.id !== void 0 ? { id: t.id } : {},
         name: t.name,
         states,
         transitions,
@@ -507,7 +547,7 @@ var OrbitalServerRuntime = class {
         const fields = entity.fields.filter(
           (f) => typeof f.name === "string" && f.name.length > 0
         );
-        this.persistence.registerEntity({ name: entity.name, fields });
+        this.persistence.registerEntity({ name: entity.name, id: entity.id, fields });
         if (this.config.debug) {
           persistLog.debug("mock:seeded", { entity: entity.name, count: this.persistence.count(entity.name) });
         }
@@ -522,7 +562,7 @@ var OrbitalServerRuntime = class {
         const auxFields = auxEntity.fields.filter(
           (f) => typeof f.name === "string" && f.name.length > 0
         );
-        this.persistence.registerEntity({ name: auxEntity.name, fields: auxFields });
+        this.persistence.registerEntity({ name: auxEntity.name, id: auxEntity.id, fields: auxFields });
         if (this.config.debug) {
           persistLog.debug("mock:seeded-auxiliary", {
             entity: auxEntity.name,
@@ -562,7 +602,8 @@ var OrbitalServerRuntime = class {
         if (!trait.listens) continue;
         for (const listener of trait.listens) {
           const { bareEvent, matcher } = parseListenSource(listener, orbitalName);
-          const cleanup = this.eventBus.on(bareEvent, async (event) => {
+          const routeKey = eventRouteKey(bareEvent, listener.eventId);
+          const cleanup = this.eventBus.on(routeKey, async (event) => {
             if (!matcher(event.source)) return;
             if (this.config.debug) {
               xOrbitalLog.debug("listen:received", () => ({
@@ -593,6 +634,7 @@ var OrbitalServerRuntime = class {
             const forwardedEntityId = pickId("entityId") ?? pickId("orbitalName");
             await this.processOrbitalEvent(orbitalName, {
               event: listener.triggers,
+              eventId: listener.triggersId,
               payload: mappedPayload,
               entityId: forwardedEntityId
             });
@@ -798,7 +840,7 @@ var OrbitalServerRuntime = class {
         const fields = entity.fields.filter(
           (f) => typeof f.name === "string" && f.name.length > 0
         );
-        this.persistence.registerEntity({ name: entity.name, fields });
+        this.persistence.registerEntity({ name: entity.name, id: entity.id, fields });
       }
     }
   }
@@ -814,146 +856,164 @@ var OrbitalServerRuntime = class {
    * response as they arrive rather than buffering and flushing at the end.
    */
   async processOrbitalEvent(orbitalName, request, onPush) {
-    await this.ensureOsHandlers();
-    await this.ensureAgentSubstrateHandlers();
-    const registered = this.orbitals.get(orbitalName);
-    if (!registered) {
-      return {
-        success: false,
-        transitioned: false,
-        states: {},
-        emittedEvents: [],
-        error: `Orbital not found: ${orbitalName}`
-      };
-    }
-    const payloadRow = request.payload?.["row"];
-    const payloadRowAsPayload = payloadRow !== null && typeof payloadRow === "object" && !Array.isArray(payloadRow) ? payloadRow : void 0;
-    const payloadRowId = payloadRowAsPayload?.["id"];
-    renderLog.debug("processOrbitalEvent:enter", {
-      orbital: orbitalName,
-      event: request.event,
-      hasPayloadRow: payloadRowAsPayload !== void 0,
-      payloadRowId: typeof payloadRowId === "string" || typeof payloadRowId === "number" ? payloadRowId : void 0,
-      entityId: request.entityId
-    });
-    busLog.debug("bus:incoming", () => ({
-      orbital: orbitalName,
-      event: request.event,
-      payload: JSON.stringify(request.payload ?? null),
-      entityId: request.entityId,
-      traitStates: JSON.stringify(
-        Array.from(registered.manager.getAllStates().entries()).map(([traitName, state]) => ({
-          traitName,
-          currentState: state.currentState
-        }))
-      )
-    }));
-    xOrbitalLog.info("processOrbitalEvent:enter", () => ({
-      orbital: orbitalName,
-      event: request.event,
-      traitsInOrbital: registered.traits.map((t) => t.name).join(","),
-      payloadActiveTraits: JSON.stringify(
-        request.payload?.["_activeTraits"] ?? null
-      )
-    }));
-    const { event, payload, entityId, user } = request;
-    const validationFailures = [];
-    for (const trait of registered.traits) {
-      const eventSchema = trait.stateMachine?.events?.find((e) => e.key === event);
-      if (eventSchema?.payloadSchema && eventSchema.payloadSchema.length > 0) {
-        validationFailures.push(
-          ...validateEventPayload(event, payload, eventSchema.payloadSchema)
+    try {
+      await this.ensureOsHandlers();
+      await this.ensureAgentSubstrateHandlers();
+      const registered = this.orbitals.get(orbitalName);
+      if (!registered) {
+        return {
+          success: false,
+          transitioned: false,
+          states: {},
+          emittedEvents: [],
+          error: `Orbital not found: ${orbitalName}`
+        };
+      }
+      const payloadRow = request.payload?.["row"];
+      const payloadRowAsPayload = payloadRow !== null && typeof payloadRow === "object" && !Array.isArray(payloadRow) ? payloadRow : void 0;
+      const payloadRowId = payloadRowAsPayload?.["id"];
+      renderLog.debug("processOrbitalEvent:enter", {
+        orbital: orbitalName,
+        event: request.event,
+        hasPayloadRow: payloadRowAsPayload !== void 0,
+        payloadRowId: typeof payloadRowId === "string" || typeof payloadRowId === "number" ? payloadRowId : void 0,
+        entityId: request.entityId
+      });
+      busLog.debug("bus:incoming", () => ({
+        orbital: orbitalName,
+        event: request.event,
+        payload: JSON.stringify(request.payload ?? null),
+        entityId: request.entityId,
+        traitStates: JSON.stringify(
+          Array.from(registered.manager.getAllStates().entries()).map(([traitName, state]) => ({
+            traitName,
+            currentState: state.currentState
+          }))
+        )
+      }));
+      xOrbitalLog.info("processOrbitalEvent:enter", () => ({
+        orbital: orbitalName,
+        event: request.event,
+        traitsInOrbital: registered.traits.map((t) => t.name).join(","),
+        payloadActiveTraits: JSON.stringify(
+          request.payload?.["_activeTraits"] ?? null
+        )
+      }));
+      const { event, eventId, payload, entityId, user } = request;
+      const validationFailures = [];
+      for (const trait of registered.traits) {
+        const eventSchema = trait.stateMachine?.events?.find((e) => e.key === event);
+        if (eventSchema?.payloadSchema && eventSchema.payloadSchema.length > 0) {
+          validationFailures.push(
+            ...validateEventPayload(event, payload, eventSchema.payloadSchema)
+          );
+        }
+      }
+      if (validationFailures.length > 0) {
+        return {
+          success: false,
+          transitioned: false,
+          states: {},
+          emittedEvents: [],
+          error: formatPayloadValidationError(validationFailures)
+        };
+      }
+      const emittedEvents = [];
+      const fetchedData = {};
+      const clientEffects = [];
+      const clientEffectsByTrait = [];
+      const effectResults = [];
+      const activeTraits = payload?._activeTraits;
+      const cleanPayload = payload ? { ...payload } : void 0;
+      if (cleanPayload) {
+        delete cleanPayload._activeTraits;
+      }
+      let entityData = {};
+      if (entityId) {
+        const stored = await this.persistence.getById(
+          registered.entity.name,
+          entityId
         );
+        if (stored) {
+          entityData = stored;
+        }
       }
-    }
-    if (validationFailures.length > 0) {
+      const entityByTrait = {};
+      for (const [name, fields] of registered.traitFieldStates) {
+        if (fields && Object.keys(fields).length > 0) {
+          entityByTrait[name] = fields;
+        }
+      }
+      const results = registered.manager.sendEvent(
+        event,
+        cleanPayload,
+        entityData,
+        entityByTrait,
+        eventId
+      );
+      const filteredResults = activeTraits && activeTraits.length > 0 ? results.filter(({ traitName }) => activeTraits.includes(traitName)) : results;
+      if (this.config.debug && activeTraits) {
+        busLog.debug("dispatch:filter-traits", () => ({
+          total: results.length,
+          active: filteredResults.length,
+          activeTraits: activeTraits.join(",")
+        }));
+      }
+      for (const { traitName, result } of filteredResults) {
+        if (result.effects.length > 0) {
+          await this.executeEffects(
+            registered,
+            traitName,
+            result.effects,
+            cleanPayload,
+            entityData,
+            entityId,
+            emittedEvents,
+            fetchedData,
+            clientEffects,
+            effectResults,
+            user,
+            clientEffectsByTrait,
+            onPush
+          );
+        }
+      }
+      const states = {};
+      for (const [name, state] of registered.manager.getAllStates()) {
+        states[name] = state.currentState;
+      }
+      const response = {
+        success: true,
+        transitioned: results.length > 0,
+        states,
+        emittedEvents
+      };
+      if (clientEffects.length > 0) {
+        response.clientEffects = clientEffects;
+      }
+      if (clientEffectsByTrait.length > 0) {
+        response.clientEffectsByTrait = clientEffectsByTrait;
+      }
+      if (effectResults.length > 0) {
+        response.effectResults = effectResults;
+      }
+      return response;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      xOrbitalLog.error("processOrbitalEvent:error", {
+        orbital: orbitalName,
+        event: request.event,
+        entityId: request.entityId,
+        error: message
+      });
       return {
         success: false,
         transitioned: false,
         states: {},
         emittedEvents: [],
-        error: formatPayloadValidationError(validationFailures)
+        error: message
       };
     }
-    const emittedEvents = [];
-    const fetchedData = {};
-    const clientEffects = [];
-    const clientEffectsByTrait = [];
-    const effectResults = [];
-    const activeTraits = payload?._activeTraits;
-    const cleanPayload = payload ? { ...payload } : void 0;
-    if (cleanPayload) {
-      delete cleanPayload._activeTraits;
-    }
-    let entityData = {};
-    if (entityId) {
-      const stored = await this.persistence.getById(
-        registered.entity.name,
-        entityId
-      );
-      if (stored) {
-        entityData = stored;
-      }
-    }
-    const entityByTrait = {};
-    for (const [name, fields] of registered.traitFieldStates) {
-      if (fields && Object.keys(fields).length > 0) {
-        entityByTrait[name] = fields;
-      }
-    }
-    const results = registered.manager.sendEvent(
-      event,
-      cleanPayload,
-      entityData,
-      entityByTrait
-    );
-    const filteredResults = activeTraits && activeTraits.length > 0 ? results.filter(({ traitName }) => activeTraits.includes(traitName)) : results;
-    if (this.config.debug && activeTraits) {
-      busLog.debug("dispatch:filter-traits", () => ({
-        total: results.length,
-        active: filteredResults.length,
-        activeTraits: activeTraits.join(",")
-      }));
-    }
-    for (const { traitName, result } of filteredResults) {
-      if (result.effects.length > 0) {
-        await this.executeEffects(
-          registered,
-          traitName,
-          result.effects,
-          cleanPayload,
-          entityData,
-          entityId,
-          emittedEvents,
-          fetchedData,
-          clientEffects,
-          effectResults,
-          user,
-          clientEffectsByTrait,
-          onPush
-        );
-      }
-    }
-    const states = {};
-    for (const [name, state] of registered.manager.getAllStates()) {
-      states[name] = state.currentState;
-    }
-    const response = {
-      success: true,
-      transitioned: results.length > 0,
-      states,
-      emittedEvents
-    };
-    if (clientEffects.length > 0) {
-      response.clientEffects = clientEffects;
-    }
-    if (clientEffectsByTrait.length > 0) {
-      response.clientEffectsByTrait = clientEffectsByTrait;
-    }
-    if (effectResults.length > 0) {
-      response.effectResults = effectResults;
-    }
-    return response;
   }
   /**
    * Execute effects from a transition
@@ -977,11 +1037,22 @@ var OrbitalServerRuntime = class {
             sourceTrait: source?.trait
           }));
         }
+        const emittingTrait = registered.traits.find((t) => t.name === traitName);
+        const emitContract = emittingTrait?.emits?.find((e) => e.event === event);
         const stamp = source ?? {
           orbital: registered.schema.name,
           trait: traitName
         };
-        this.eventBus.emit(event, eventPayload, stamp);
+        if (stamp.orbitalId === void 0 && registered.schema.id !== void 0) {
+          stamp.orbitalId = registered.schema.id;
+        }
+        if (stamp.traitId === void 0 && emittingTrait?.id !== void 0) {
+          stamp.traitId = emittingTrait.id;
+        }
+        if (stamp.eventId === void 0 && emitContract?.eventId !== void 0) {
+          stamp.eventId = emitContract.eventId;
+        }
+        this.eventBus.emit(event, eventPayload, stamp, eventRouteKey(event, stamp.eventId));
         const emittedItem = { event, payload: eventPayload, source: stamp };
         emittedEvents.push(emittedItem);
         onPush?.({ type: "event", data: emittedItem });
@@ -1446,9 +1517,22 @@ var OrbitalServerRuntime = class {
     };
     const traitDef = registered.traits.find((t) => t.name === traitName);
     const declaredDefaults = collectDeclaredConfigDefaults(traitDef);
-    const callSiteOverride = registered.configByTrait.get(traitName);
-    if (declaredDefaults || callSiteOverride) {
-      bindings.config = { ...declaredDefaults ?? {}, ...callSiteOverride ?? {} };
+    const resolvedDefaults = this.resolvedTraitConfigs[traitName];
+    const callSiteOverrideRaw = registered.configByTrait.get(traitName);
+    const callSiteOverride = callSiteOverrideRaw ? resolveCallSitePayloadCaptures(
+      Object.fromEntries(
+        Object.entries(callSiteOverrideRaw).filter(
+          ([, v]) => !(typeof v === "string" && v.startsWith("@config."))
+        )
+      ),
+      payload
+    ) : void 0;
+    if (declaredDefaults || resolvedDefaults || callSiteOverride) {
+      bindings.config = {
+        ...declaredDefaults ?? {},
+        ...resolvedDefaults ?? {},
+        ...callSiteOverride ?? {}
+      };
     }
     const entityFieldDefaults = collectDeclaredEntityDefaults(registered.entity);
     const traitFieldState = registered.traitFieldStates.get(traitName);
@@ -1639,7 +1723,15 @@ var OrbitalServerRuntime = class {
         continue;
       }
       const foreignKeyField = relationField.name;
-      const relatedEntityType = relationField.relation.entity;
+      let relatedEntityType = relationField.relation.entity;
+      if (relationField.relation.entityId) {
+        for (const registered of this.orbitals.values()) {
+          if (registered.entity.id === relationField.relation.entityId) {
+            relatedEntityType = registered.entity.name;
+            break;
+          }
+        }
+      }
       const cardinality = relationField.relation.cardinality || "one";
       const foreignKeyIds = /* @__PURE__ */ new Set();
       for (const entity of entities) {
@@ -1877,7 +1969,7 @@ function parseListenSource(listener, listenerOrbital) {
   if (explicit && typeof explicit === "object") {
     return {
       bareEvent: listener.event,
-      matcher: buildMatcher(explicit, listenerOrbital)
+      matcher: buildSourceMatcher(explicit, listenerOrbital)
     };
   }
   const key = listener.event;
@@ -1892,7 +1984,7 @@ function parseListenSource(listener, listenerOrbital) {
     }
     return {
       bareEvent: eventName,
-      matcher: buildMatcher(
+      matcher: buildSourceMatcher(
         { kind: "trait", trait: sourceOrStar },
         listenerOrbital
       )
@@ -1904,20 +1996,10 @@ function parseListenSource(listener, listenerOrbital) {
     const orbital = parts.slice(0, parts.length - 2).join(".");
     return {
       bareEvent: eventName,
-      matcher: buildMatcher({ kind: "orbital", orbital, trait }, listenerOrbital)
+      matcher: buildSourceMatcher({ kind: "orbital", orbital, trait }, listenerOrbital)
     };
   }
   return { bareEvent: key, matcher: () => true };
 }
-function buildMatcher(src, listenerOrbital) {
-  if (src.kind === "any") return () => true;
-  if (src.kind === "trait") {
-    const wantedTrait2 = src.trait;
-    return (source) => !!source && source.orbital === listenerOrbital && source.trait === wantedTrait2;
-  }
-  const wantedOrbital = src.orbital;
-  const wantedTrait = src.trait;
-  return (source) => !!source && source.orbital === wantedOrbital && source.trait === wantedTrait;
-}
 
 export { OrbitalServerRuntime, createOrbitalServerRuntime };

package/dist/ServerBridge.d.ts

@@ -1,4 +1,4 @@
-import { I as IEventBus } from './types-D-9feVsj.js';
+import { I as IEventBus } from './types-C8RsO0xa.js';
 import { EventPayload } from '@almadar/core';
 
 /**