@almadar/runtime 6.33.0 → 6.35.0

package/dist/{OrbitalServerRuntime-Cep380it.d.ts → OrbitalServerRuntime-BY-qzEQ_.d.ts}

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, C as ConfigContext, d as TraitState, e as TransitionResult, f as EvaluationContextExtensions, E as EffectHandlers } from './types-ConZnrpe.js';
-import { EventPayload, EntityRow, Orbital, ServiceCallResult, TraitConfig, DeclaredTraitConfig, Entity, OrbitalSchema, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, TraitTick } from '@almadar/core';
+import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, d as TraitState, C as ConfigContext, e as TransitionResult, f as EvaluationContextExtensions, E as EffectHandlers } from './types-C8RsO0xa.js';
+import { EventPayload, EventId, EntityRow, Orbital, ServiceCallResult, TraitConfig, DeclaredTraitConfig, Entity, OrbitalSchema, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, TraitTick } from '@almadar/core';
 
 /**
  * EventBus - Platform-Agnostic Pub/Sub Implementation
@@ -47,7 +47,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?: EventPayload, source?: RuntimeEvent['source']): void;
+    emit(type: string, payload?: EventPayload, source?: RuntimeEvent['source'], routingKey?: string): void;
     /**
      * Subscribe to an event type
      */
@@ -101,7 +101,7 @@ declare function createInitialTraitState(trait: TraitDefinition): TraitState;
  * when multiple sibling transitions share the same `from`/`event` and
  * disambiguate by guard.
  */
-declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string): TraitDefinition['transitions'][0] | undefined;
+declare function findTransition(trait: TraitDefinition, currentState: string, eventKey: string, eventId?: EventId): TraitDefinition['transitions'][0] | undefined;
 /**
  * Normalize event key - strip UI: prefix if present.
  */
@@ -116,6 +116,12 @@ interface ProcessEventOptions {
     trait: TraitDefinition;
     /** Event key to process */
     eventKey: string;
+    /**
+     * V4 dual-carry id sibling of `eventKey` — the id of the fired event,
+     * when known. Threaded to `findMatchingTransitions` for id-primary
+     * matching; absent means name-only dispatch (legacy).
+     */
+    eventId?: EventId;
     /** Event payload */
     payload?: EventPayload;
     /** Entity data for binding resolution */
@@ -179,6 +185,15 @@ interface ProcessEventOptions {
 declare function processEvent(options: ProcessEventOptions): TransitionResult;
 declare class StateMachineManager {
     private traits;
+    /**
+     * V4 identity index: trait id → trait name. Populated for traits that
+     * carry an `id` (ledger-backed schemas). Lets callers resolve a trait's
+     * state by its stable id, which survives a mid-session rename — the
+     * name-keyed maps are re-pointed on rename via {@link renameTrait}, but
+     * an id holder never has to observe the rename at all. Empty for legacy
+     * id-free schemas, where every lookup stays name-keyed (unchanged).
+     */
+    private traitIdToName;
     /**
      * Per-trait call-site config, surfaced to guard expressions so
      * `@config.X` resolves at runtime. Populated by the orbital's
@@ -217,6 +232,26 @@ declare class StateMachineManager {
      * Add a trait to the manager.
      */
     addTrait(trait: TraitDefinition): void;
+    /**
+     * Resolve a trait by its V4 id. Returns undefined when no trait carries
+     * that id (legacy schema, or unknown id). Exact-match only — no name
+     * similarity.
+     */
+    getTraitById(traitId: string): TraitDefinition | undefined;
+    /**
+     * Get a trait's current state by its V4 id (id-first lookup). Falls back
+     * to `undefined` when the id is unknown. The id survives a rename, so a
+     * holder of the id reads the right state without ever seeing the new name.
+     */
+    getStateById(traitId: string, entityId?: string): TraitState | undefined;
+    /**
+     * Apply a mid-session trait rename: re-point the name-keyed maps from
+     * `oldName` to `newName`, preserving live state, queues, and the id
+     * index. A no-op when the trait isn't registered under `oldName`. This
+     * is the interpreter-side of a ledger `curName` edit for the trait's own
+     * name-keyed storage; id-keyed references need no update.
+     */
+    renameTrait(oldName: string, newName: string): void;
     /**
      * Bind the call-site config for a trait so guard `@config.X`
      * resolves at runtime. Typically called by the orbital
@@ -256,7 +291,7 @@ declare class StateMachineManager {
     /**
      * Check if a trait can handle an event from its current state.
      */
-    canHandleEvent(traitName: string, eventKey: string, entityId?: string): boolean;
+    canHandleEvent(traitName: string, eventKey: string, entityId?: string, eventId?: EventId): boolean;
     /**
      * Send an event to all traits.
      *
@@ -267,9 +302,13 @@ declare class StateMachineManager {
      * `@entity.X` see prior step writes — required for [runtime] entities
      * that have no persistence row to reload.
      *
+     * `eventId` is the V4 dual-carry id sibling of `eventKey` (see
+     * {@link ProcessEventOptions.eventId}) — additive and optional, threaded
+     * through to `processEvent` for id-primary transition matching.
+     *
      * @returns Array of transition results (one per trait that had a matching transition)
      */
-    sendEvent(eventKey: string, payload?: EventPayload, entityData?: EntityRow, entityByTrait?: Record<string, EntityRow>): Array<{
+    sendEvent(eventKey: string, payload?: EventPayload, entityData?: EntityRow, entityByTrait?: Record<string, EntityRow>, eventId?: EventId, targetTrait?: string): Array<{
         traitName: string;
         result: TransitionResult;
     }>;
@@ -280,7 +319,7 @@ declare class StateMachineManager {
      * 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, entityByTrait?: Record<string, EntityRow>): void;
+    enqueueEvent(eventKey: string, payload?: EventPayload, entityData?: EntityRow, entityByTrait?: Record<string, EntityRow>, eventId?: EventId): void;
     /**
      * Drain a single (trait, entity) pair's event queue, processing
      * events sequentially. Pass `entityId` to drain a specific entity
@@ -898,8 +937,21 @@ interface RegisteredOrbital {
  */
 interface OrbitalEventRequest {
     event: string;
+    /**
+     * V4 dual-carry id sibling of `event` — the fired event's id, when known
+     * (e.g. threaded from a `listens[].triggersId`). Optional; absent means
+     * the state machine dispatches by name only (legacy).
+     */
+    eventId?: EventId;
     payload?: EventPayload;
     entityId?: string;
+    /**
+     * Scoped-listen delivery: dispatch to THIS trait only. A listens-matched
+     * trigger is addressed to the listening trait; without this, a trigger
+     * renamed to INIT broadcast orbital-wide and re-ran every trait's
+     * initializer (R-SCOPED-LISTEN-INIT-RENAME-FREEZE re-fire cascade).
+     */
+    targetTrait?: string;
     /** User context for @user bindings (from Firebase auth) */
     user?: {
         uid: string;

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-Cep380it.js';
-import './types-ConZnrpe.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-BY-qzEQ_.js';
+import './types-C8RsO0xa.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, resolveCallSitePayloadCaptures, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-JZDLN2FS.js';
-export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-JZDLN2FS.js';
+import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, resolveCallSitePayloadCaptures, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-VCEF5JOX.js';
+export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-VCEF5JOX.js';
 import { isValidCronExpression } from './chunk-OU3ITB5S.js';
 import './chunk-OQJIK6PZ.js';
 import './chunk-SCRAHWOC.js';
@@ -9,6 +9,29 @@ import * as nodeModule from 'module';
 import { evaluateGuard, evaluate } from '@almadar/evaluator';
 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) {
@@ -454,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,
@@ -521,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) });
         }
@@ -536,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,
@@ -576,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", () => ({
@@ -607,8 +634,10 @@ var OrbitalServerRuntime = class {
             const forwardedEntityId = pickId("entityId") ?? pickId("orbitalName");
             await this.processOrbitalEvent(orbitalName, {
               event: listener.triggers,
+              eventId: listener.triggersId,
               payload: mappedPayload,
-              entityId: forwardedEntityId
+              entityId: forwardedEntityId,
+              targetTrait: trait.name
             });
           });
           this.listenerCleanups.push(cleanup);
@@ -812,7 +841,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 });
       }
     }
   }
@@ -871,7 +900,8 @@ var OrbitalServerRuntime = class {
           request.payload?.["_activeTraits"] ?? null
         )
       }));
-      const { event, payload, entityId, user } = request;
+      const { event, eventId, payload, entityId, user } = request;
+      const targetTrait = request.targetTrait ?? payload?.["_targetTrait"];
       const validationFailures = [];
       for (const trait of registered.traits) {
         const eventSchema = trait.stateMachine?.events?.find((e) => e.key === event);
@@ -899,6 +929,7 @@ var OrbitalServerRuntime = class {
       const cleanPayload = payload ? { ...payload } : void 0;
       if (cleanPayload) {
         delete cleanPayload._activeTraits;
+        delete cleanPayload._targetTrait;
       }
       let entityData = {};
       if (entityId) {
@@ -920,7 +951,9 @@ var OrbitalServerRuntime = class {
         event,
         cleanPayload,
         entityData,
-        entityByTrait
+        entityByTrait,
+        eventId,
+        targetTrait
       );
       const filteredResults = activeTraits && activeTraits.length > 0 ? results.filter(({ traitName }) => activeTraits.includes(traitName)) : results;
       if (this.config.debug && activeTraits) {
@@ -1008,11 +1041,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 });
@@ -1683,7 +1727,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) {
@@ -1921,7 +1973,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;
@@ -1936,7 +1988,7 @@ function parseListenSource(listener, listenerOrbital) {
     }
     return {
       bareEvent: eventName,
-      matcher: buildMatcher(
+      matcher: buildSourceMatcher(
         { kind: "trait", trait: sourceOrStar },
         listenerOrbital
       )
@@ -1948,20 +2000,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-ConZnrpe.js';
+import { I as IEventBus } from './types-C8RsO0xa.js';
 import { EventPayload } from '@almadar/core';
 
 /**