@almadar/runtime 6.33.0 → 6.34.0

package/dist/{chunk-JZDLN2FS.js → chunk-TRA44DDY.js}

@@ -5,7 +5,7 @@ import { createLogger, setNamespaceLevel } from '@almadar/logger';
 import { createMinimalContext, resolveBinding, evaluate, evaluateGuard, SExpressionEvaluator } from '@almadar/evaluator';
 export { createMinimalContext } from '@almadar/evaluator';
 import { isKnownStdOperator } from '@almadar/std/registry';
-import { OrbitalSchemaSchema, isInlineTrait, isEntityCall, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef, configRefEventKnob, normalizeCallSiteConfigToValues, resolveConfigRefEventName } from '@almadar/core';
+import { OrbitalSchemaSchema, isInlineTrait, isEntityCall, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef, isReferenceConfigType, configRefEventKnob, normalizeCallSiteConfigToValues, resolveConfigRefEventName } from '@almadar/core';
 export { normalizeCallSiteConfigToValues } from '@almadar/core';
 
 var log = createLogger("almadar:runtime:eventbus");
@@ -26,7 +26,7 @@ var EventBus = class {
    * beyond `maxDepth`, the event is dropped and an error is logged.
    * This prevents infinite loops from circular emit/listen chains.
    */
-  emit(type, payload, source) {
+  emit(type, payload, source, routingKey) {
     if (this.depth >= this.maxDepth) {
       log.error("circular event loop dropped", { type, depth: this.depth, maxDepth: this.maxDepth });
       return;
@@ -37,12 +37,13 @@ var EventBus = class {
       timestamp: Date.now(),
       source
     };
-    const listeners = this.listeners.get(type);
+    const deliveryKey = routingKey ?? type;
+    const listeners = this.listeners.get(deliveryKey);
     const listenerCount = listeners?.size ?? 0;
     if (listenerCount > 0) {
       log.debug("emit", { type, listenerCount, depth: this.depth });
     } else {
-      log.warn("emit no listeners", { type });
+      log.debug("emit no listeners", { type });
     }
     this.depth++;
     try {
@@ -394,6 +395,7 @@ function interpolateValue(value, ctx) {
   }
   return value;
 }
+var inFlightConfigRecursions = /* @__PURE__ */ new Set();
 function interpolateString(value, ctx) {
   if (value.startsWith("@") && isPureBinding(value)) {
     if (isClientOnlyBinding(value)) {
@@ -402,6 +404,15 @@ function interpolateString(value, ctx) {
     }
     const resolved = resolveBinding(value, ctx);
     bindLog.debug("resolve", { binding: value, resolvedType: typeof resolved });
+    if (value.startsWith("@config.") && resolved !== null && typeof resolved === "object" && containsBindings(resolved) && !inFlightConfigRecursions.has(value)) {
+      inFlightConfigRecursions.add(value);
+      try {
+        bindLog.debug("resolve:config-recurse", { binding: value });
+        return interpolateValue(resolved, ctx);
+      } finally {
+        inFlightConfigRecursions.delete(value);
+      }
+    }
     return resolved;
   }
   if (value.includes("@")) {
@@ -443,12 +454,25 @@ function interpolateArray(value, ctx) {
   let anyChanged = false;
   for (let i = 0; i < value.length; i++) {
     const item = value[i];
+    if (Array.isArray(item) && isRenderChildrenMap(item)) {
+      const expanded = evaluate(item, ctx);
+      if (Array.isArray(expanded)) {
+        for (const node of expanded) mapped.push(node);
+      }
+      anyChanged = true;
+      continue;
+    }
     const interpolated = interpolateValue(item, ctx);
     mapped.push(interpolated);
     if (interpolated !== item) anyChanged = true;
   }
   return anyChanged ? mapped : value;
 }
+function isRenderChildrenMap(value) {
+  if (value.length !== 3 || value[0] !== "array/map") return false;
+  const lambda = value[2];
+  return Array.isArray(lambda) && lambda.length === 3 && lambda[0] === "fn" && typeof lambda[1] === "string";
+}
 function isSExpression(value) {
   if (value.length === 0) return false;
   const first = value[0];
@@ -526,19 +550,21 @@ function createInitialTraitState(trait) {
     context: {}
   };
 }
-function findMatchingTransitions(trait, currentState, eventKey) {
+function findMatchingTransitions(trait, currentState, eventKey, eventId) {
   if (!trait.transitions || trait.transitions.length === 0) {
     return [];
   }
   return trait.transitions.filter((t) => {
-    if (Array.isArray(t.from)) {
-      return t.from.includes(currentState) && t.event === eventKey;
+    const fromMatches = Array.isArray(t.from) ? t.from.includes(currentState) : t.from === currentState;
+    if (!fromMatches) return false;
+    if (eventId && t.eventId) {
+      return t.eventId === eventId;
     }
-    return t.from === currentState && t.event === eventKey;
+    return t.event === eventKey;
   });
 }
-function findTransition(trait, currentState, eventKey) {
-  return findMatchingTransitions(trait, currentState, eventKey)[0];
+function findTransition(trait, currentState, eventKey, eventId) {
+  return findMatchingTransitions(trait, currentState, eventKey, eventId)[0];
 }
 function normalizeEventKey(eventKey) {
   if (!eventKey) return "";
@@ -549,6 +575,7 @@ function processEvent(options) {
     traitState,
     trait,
     eventKey,
+    eventId,
     payload,
     entityData,
     config,
@@ -557,7 +584,7 @@ function processEvent(options) {
     contextExtensions
   } = options;
   const normalizedEvent = normalizeEventKey(eventKey);
-  const candidates = findMatchingTransitions(trait, traitState.currentState, normalizedEvent);
+  const candidates = findMatchingTransitions(trait, traitState.currentState, normalizedEvent, eventId);
   if (candidates.length === 0) {
     smLog.debug("noTransition", { trait: trait.name, event: normalizedEvent, currentState: traitState.currentState });
     return {
@@ -676,6 +703,15 @@ function compositeKey(traitName, scope) {
 }
 var StateMachineManager = class {
   traits = /* @__PURE__ */ new Map();
+  /**
+   * 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).
+   */
+  traitIdToName = /* @__PURE__ */ new Map();
   /**
    * Per-trait call-site config, surfaced to guard expressions so
    * `@config.X` resolves at runtime. Populated by the orbital's
@@ -726,6 +762,69 @@ var StateMachineManager = class {
    */
   addTrait(trait) {
     this.traits.set(trait.name, trait);
+    if (trait.id !== void 0) {
+      this.traitIdToName.set(trait.id, trait.name);
+    }
+  }
+  /**
+   * 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) {
+    const name = this.traitIdToName.get(traitId);
+    return name === void 0 ? void 0 : this.traits.get(name);
+  }
+  /**
+   * 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, entityId) {
+    const name = this.traitIdToName.get(traitId);
+    return name === void 0 ? void 0 : this.getState(name, entityId);
+  }
+  /**
+   * 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, newName) {
+    const trait = this.traits.get(oldName);
+    if (!trait || oldName === newName) return;
+    const renamed = { ...trait, name: newName };
+    this.traits.delete(oldName);
+    this.traits.set(newName, renamed);
+    if (renamed.id !== void 0) {
+      this.traitIdToName.set(renamed.id, newName);
+    }
+    const remap = (m) => {
+      const prefix2 = `${oldName}::`;
+      for (const key of [...m.keys()]) {
+        if (key.startsWith(prefix2)) {
+          const scope = key.slice(prefix2.length);
+          const v = m.get(key);
+          m.delete(key);
+          m.set(`${newName}::${scope}`, v);
+        }
+      }
+    };
+    remap(this.states);
+    remap(this.queues);
+    const prefix = `${oldName}::`;
+    for (const key of [...this.processing]) {
+      if (key.startsWith(prefix)) {
+        this.processing.delete(key);
+        this.processing.add(`${newName}::${key.slice(prefix.length)}`);
+      }
+    }
+    const cfg = this.traitConfigs.get(oldName);
+    if (cfg !== void 0) {
+      this.traitConfigs.set(newName, cfg);
+      this.traitConfigs.delete(oldName);
+    }
   }
   /**
    * Bind the call-site config for a trait so guard `@config.X`
@@ -744,6 +843,10 @@ var StateMachineManager = class {
    * Remove a trait from the manager.
    */
   removeTrait(traitName) {
+    const removed = this.traits.get(traitName);
+    if (removed?.id !== void 0) {
+      this.traitIdToName.delete(removed.id);
+    }
     this.traits.delete(traitName);
     const prefix = `${traitName}::`;
     for (const key of [...this.states.keys()]) {
@@ -831,11 +934,11 @@ var StateMachineManager = class {
   /**
    * Check if a trait can handle an event from its current state.
    */
-  canHandleEvent(traitName, eventKey, entityId) {
+  canHandleEvent(traitName, eventKey, entityId, eventId) {
     const trait = this.traits.get(traitName);
     const state = this.getOrInitState(traitName, entityId ?? SINGLETON_SCOPE);
     if (!trait || !state) return false;
-    return !!findTransition(trait, state.currentState, normalizeEventKey(eventKey));
+    return !!findTransition(trait, state.currentState, normalizeEventKey(eventKey), eventId);
   }
   /**
    * Send an event to all traits.
@@ -847,9 +950,13 @@ var StateMachineManager = class {
    * `@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, payload, entityData, entityByTrait) {
+  sendEvent(eventKey, payload, entityData, entityByTrait, eventId) {
     const results = [];
     const scope = scopeOf(entityData);
     for (const [traitName, trait] of this.traits) {
@@ -861,6 +968,7 @@ var StateMachineManager = class {
         traitState,
         trait,
         eventKey,
+        eventId,
         payload,
         entityData: perTraitEntity,
         config: this.traitConfigs.get(traitName),
@@ -902,12 +1010,12 @@ var StateMachineManager = class {
    * trait to process them sequentially (actor-model guarantee: one event
    * at a time per trait, effects fully awaited before the next event).
    */
-  enqueueEvent(eventKey, payload, entityData, entityByTrait) {
+  enqueueEvent(eventKey, payload, entityData, entityByTrait, eventId) {
     const scope = scopeOf(entityData);
     for (const [traitName] of this.traits) {
       const key = compositeKey(traitName, scope);
       const queue = this.queues.get(key) ?? [];
-      queue.push({ eventKey, payload, entityData, entityByTrait });
+      queue.push({ eventKey, eventId, payload, entityData, entityByTrait });
       this.queues.set(key, queue);
     }
   }
@@ -932,6 +1040,7 @@ var StateMachineManager = class {
         traitState,
         trait,
         eventKey: entry.eventKey,
+        eventId: entry.eventId,
         payload: entry.payload,
         entityData: perTraitEntity,
         config: this.traitConfigs.get(traitName),
@@ -2212,6 +2321,8 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   stores = /* @__PURE__ */ new Map();
   schemas = /* @__PURE__ */ new Map();
   idCounters = /* @__PURE__ */ new Map();
+  /** entityId -> normalized store name, so relation lookups can prefer the id sibling over `relation.entity` name-matching. */
+  storeNameById = /* @__PURE__ */ new Map();
   config;
   constructor(config = {}) {
     this.config = {
@@ -2263,6 +2374,9 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   registerEntity(schema, seedCount) {
     const normalized = schema.name.toLowerCase();
     this.schemas.set(normalized, schema);
+    if (schema.id) {
+      this.storeNameById.set(schema.id, normalized);
+    }
     if (schema.seedData && schema.seedData.length > 0) {
       this.seedFromInstances(schema.name, schema.seedData);
     } else {
@@ -2294,7 +2408,8 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
       if (relationFields.length === 0) continue;
       for (const row of store.values()) {
         for (const field of relationFields) {
-          const targetStore = this.stores.get(field.relation.entity.toLowerCase());
+          const targetNormalized = (field.relation.entityId && this.storeNameById.get(field.relation.entityId)) ?? field.relation.entity.toLowerCase();
+          const targetStore = this.stores.get(targetNormalized);
           if (!targetStore || targetStore.size === 0) continue;
           const selfId = row["id"];
           const sameStore = targetStore === store;
@@ -2972,7 +3087,7 @@ async function getExternalLoaderModule() {
     return null;
   }
   try {
-    externalLoaderModule = await import('./external-loader-OPXVTNC4.js');
+    externalLoaderModule = await import('./external-loader-FNK5AU6U.js');
     return externalLoaderModule;
   } catch {
     return null;
@@ -3307,10 +3422,10 @@ function substituteConfig(expr, subs) {
 function buildTemplate(trait) {
   const raw = renderOnlyTemplate(trait);
   const emits = trait.emits ?? [];
-  if (raw === null) return { template: null, emits };
+  if (raw === null) return { template: null, emits, traitName: trait.name, id: trait.id, embedIds: trait.traitEmbedIds };
   const defaults = collectDeclaredConfigDefaults(trait);
   const template = defaults ? substituteConfig(raw, defaults) : raw;
-  return { template, emits };
+  return { template, emits, traitName: trait.name, id: trait.id, embedIds: trait.traitEmbedIds };
 }
 function isLambdaForm(expr) {
   return expr.length === 3 && (expr[0] === "fn" || expr[0] === "lambda");
@@ -3320,7 +3435,8 @@ function spliceExpr(expr, inLambda, st) {
     if (!inLambda || !expr.startsWith(TRAIT_BINDING_PREFIX)) return expr;
     const name = expr.slice(TRAIT_BINDING_PREFIX.length);
     if (name.length === 0 || name.includes(".")) return expr;
-    const entry = st.templates.get(name);
+    const embedId = st.embedIds?.[name];
+    const entry = (embedId !== void 0 ? st.templatesById.get(embedId) : void 0) ?? st.templates.get(name);
     if (entry === void 0) return expr;
     if (entry.template === null) {
       throw new LambdaSpliceError(
@@ -3330,10 +3446,13 @@ function spliceExpr(expr, inLambda, st) {
     }
     if (st.visiting.includes(name)) return expr;
     st.visiting.push(name);
+    const prevEmbedIds = st.embedIds;
+    st.embedIds = entry.embedIds;
     const expanded = spliceExpr(entry.template, true, st);
+    st.embedIds = prevEmbedIds;
     st.visiting.pop();
-    for (const emit of entry.emits) st.merged.push([name, emit]);
-    st.spliced.add(name);
+    for (const emit of entry.emits) st.merged.push([entry.traitName, emit]);
+    st.spliced.add(entry.traitName);
     st.changed = true;
     return expanded;
   }
@@ -3382,28 +3501,38 @@ function mergeWrapperEmits(host, incoming) {
   return emits;
 }
 function removeConsumedWrappers(traits, pages, spliced) {
+  const idToName = /* @__PURE__ */ new Map();
+  for (const { trait } of traits) {
+    if (trait.id) idToName.set(trait.id, trait.name);
+  }
   for (; ; ) {
     const stillReferenced = /* @__PURE__ */ new Set();
     for (const { trait } of traits) {
+      const rawTokens = /* @__PURE__ */ new Set();
       for (const t of trait.stateMachine?.transitions ?? []) {
         if (t.guard !== void 0 && t.guard !== null) {
-          collectTraitRefsFromValue(t.guard, stillReferenced);
+          collectTraitRefsFromValue(t.guard, rawTokens);
         }
-        collectTraitRefsFromEffects(t.effects, stillReferenced);
+        collectTraitRefsFromEffects(t.effects, rawTokens);
       }
       for (const tick of trait.ticks ?? []) {
         if (tick.guard !== void 0 && tick.guard !== null) {
-          collectTraitRefsFromValue(tick.guard, stillReferenced);
+          collectTraitRefsFromValue(tick.guard, rawTokens);
         }
-        collectTraitRefsFromEffects(tick.effects, stillReferenced);
+        collectTraitRefsFromEffects(tick.effects, rawTokens);
       }
       if (trait.config) {
         for (const field of Object.values(trait.config)) {
           if (field && typeof field === "object" && "default" in field && field.default !== void 0) {
-            collectTraitRefsFromValue(field.default, stillReferenced);
+            collectTraitRefsFromValue(field.default, rawTokens);
           }
         }
       }
+      for (const token of rawTokens) {
+        const embedId = trait.traitEmbedIds?.[token];
+        const resolvedName = (embedId !== void 0 ? idToName.get(embedId) : void 0) ?? token;
+        stillReferenced.add(resolvedName);
+      }
     }
     const removable = /* @__PURE__ */ new Set();
     for (const { trait } of traits) {
@@ -3435,14 +3564,19 @@ function removeConsumedWrappers(traits, pages, spliced) {
 function spliceLambdaTraitRefs(traits, pages) {
   if (traits.length === 0) return;
   const templates = /* @__PURE__ */ new Map();
+  const templatesById = /* @__PURE__ */ new Map();
   for (const { trait } of traits) {
-    templates.set(trait.name, buildTemplate(trait));
+    const entry = buildTemplate(trait);
+    templates.set(trait.name, entry);
+    if (trait.id) templatesById.set(trait.id, entry);
   }
   const spliced = /* @__PURE__ */ new Set();
   for (const resolved of traits) {
     const host = resolved.trait;
     const st = {
       templates,
+      templatesById,
+      embedIds: host.traitEmbedIds,
       // Seed with the host itself so a self-reference never self-splices.
       visiting: [host.name],
       merged: [],
@@ -3477,6 +3611,42 @@ function spliceLambdaTraitRefs(traits, pages) {
 
 // src/resolver/reference-resolver.ts
 var refResolverLog = createLogger("almadar:runtime:ref-resolver");
+function indexOrbitalNodes(orbital, idIndex) {
+  for (const traitRef of orbital.traits ?? []) {
+    if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+      const trait = traitRef;
+      if (trait.id) {
+        idIndex.set(trait.id, { kind: "trait", node: trait });
+      }
+      for (const ev of trait.stateMachine?.events ?? []) {
+        if (ev.id) {
+          idIndex.set(ev.id, { kind: "event", node: ev });
+        }
+      }
+    }
+  }
+  const entityRef = orbital.entity;
+  if (entityRef && typeof entityRef !== "string" && !("extends" in entityRef) && entityRef.id) {
+    const entity = entityRef;
+    idIndex.set(entity.id, { kind: "entity", node: entity });
+  }
+  for (const pageRef of orbital.pages ?? []) {
+    if (typeof pageRef !== "string" && !("ref" in pageRef)) {
+      const page = pageRef;
+      if (page.id) {
+        idIndex.set(page.id, { kind: "page", node: page });
+      }
+    }
+  }
+}
+function buildIdIndex(orbital, orbitals) {
+  const idIndex = /* @__PURE__ */ new Map();
+  indexOrbitalNodes(orbital, idIndex);
+  for (const imported of orbitals.values()) {
+    indexOrbitalNodes(imported.orbital, idIndex);
+  }
+  return idIndex;
+}
 function renameEventsInRenderUiConfig(node, rename) {
   if (node === null || node === void 0) return node;
   if (Array.isArray(node)) {
@@ -3526,25 +3696,30 @@ function renameEventsInEffects(effects, rename) {
     return effect;
   });
 }
-function renameEntityInRenderUiConfig(node, oldName, newName) {
+var REBIND_ENTITY_PROPS = /* @__PURE__ */ new Set(["entity"]);
+var ID_ENTITY_PROPS = /* @__PURE__ */ new Set(["entity", "entityType", "source"]);
+function renameEntityInRenderUiConfig(node, rename, props) {
   if (node === null || node === void 0) return node;
   if (Array.isArray(node)) {
-    return node.map((item) => renameEntityInRenderUiConfig(item, oldName, newName));
+    return node.map((item) => renameEntityInRenderUiConfig(item, rename, props));
   }
   if (typeof node !== "object") return node;
   const obj = node;
   const next = { ...obj };
   for (const [key, value] of Object.entries(obj)) {
-    if (key === "entity" && value === oldName) {
-      next[key] = newName;
-      continue;
+    if (props.has(key) && typeof value === "string") {
+      const replaced = rename(value);
+      if (replaced !== void 0) {
+        next[key] = replaced;
+        continue;
+      }
     }
-    next[key] = renameEntityInRenderUiConfig(value, oldName, newName);
+    next[key] = renameEntityInRenderUiConfig(value, rename, props);
   }
   return next;
 }
-function renameEntityInEffects(effects, oldName, newName) {
-  return effects.map((effect) => renameEntityInEffect(effect, oldName, newName));
+function renameEntityInEffects(effects, rename, props) {
+  return effects.map((effect) => renameEntityInEffect(effect, rename, props));
 }
 var ENTITY_AT_POS_1 = /* @__PURE__ */ new Set(["fetch", "ref", "deref", "spawn"]);
 var ALL_ARGS_ARE_EFFECTS = /* @__PURE__ */ new Set([
@@ -3563,20 +3738,22 @@ var ARGS_FROM_POS_2_ARE_EFFECTS = /* @__PURE__ */ new Set([
   "async/throttle",
   "async/interval"
 ]);
-function renameEntityInEffect(effect, oldName, newName) {
+function renameEntityInEffect(effect, rename, props) {
   if (!Array.isArray(effect) || effect.length === 0) return effect;
   const op = effect[0];
   if (typeof op !== "string") return effect;
   if (op === "render-ui" && effect.length >= 3) {
     const [, slot, config, ...rest] = effect;
-    const nextConfig = renameEntityInRenderUiConfig(config, oldName, newName);
+    const nextConfig = renameEntityInRenderUiConfig(config, rename, props);
     return [op, slot, nextConfig, ...rest];
   }
-  if (op === "persist" && effect.length >= 3 && effect[2] === oldName) {
-    return [op, effect[1], newName, ...effect.slice(3)];
+  if (op === "persist" && effect.length >= 3 && typeof effect[2] === "string") {
+    const replaced = rename(effect[2]);
+    if (replaced !== void 0) return [op, effect[1], replaced, ...effect.slice(3)];
   }
-  if (ENTITY_AT_POS_1.has(op) && effect[1] === oldName) {
-    return [op, newName, ...effect.slice(2)];
+  if (ENTITY_AT_POS_1.has(op) && typeof effect[1] === "string") {
+    const replaced = rename(effect[1]);
+    if (replaced !== void 0) return [op, replaced, ...effect.slice(2)];
   }
   const skipFirstNonEffectArg = ARGS_FROM_POS_2_ARE_EFFECTS.has(op);
   const recurseAll = ALL_ARGS_ARE_EFFECTS.has(op);
@@ -3585,7 +3762,7 @@ function renameEntityInEffect(effect, oldName, newName) {
     return effect.map((arg, i) => {
       if (i < startIndex) return arg;
       if (Array.isArray(arg)) {
-        return renameEntityInEffect(arg, oldName, newName);
+        return renameEntityInEffect(arg, rename, props);
       }
       return arg;
     });
@@ -3597,11 +3774,12 @@ function applyLinkedEntityRename(trait, linkedEntity) {
   if (!linkedEntity || !atomLinked || linkedEntity === atomLinked) return trait;
   const sm = trait.stateMachine;
   if (!sm) return { ...trait, linkedEntity };
+  const rename = (name) => name === atomLinked ? linkedEntity : void 0;
   const nextTransitions = (sm.transitions ?? []).map((t) => {
     const nextEffects = t.effects ? renameEntityInEffects(
       t.effects,
-      atomLinked,
-      linkedEntity
+      rename,
+      REBIND_ENTITY_PROPS
     ) : t.effects;
     return { ...t, effects: nextEffects };
   });
@@ -3617,6 +3795,85 @@ function applyLinkedEntityRename(trait, linkedEntity) {
     stateMachine: { ...sm, transitions: nextTransitions }
   };
 }
+function resolveEntityTokensById(trait, idIndex) {
+  const map = trait.entityRefIds;
+  if (!map) return trait;
+  const rewrites = /* @__PURE__ */ new Map();
+  for (const [tokenName, entityId] of Object.entries(map)) {
+    const entry = idIndex.get(entityId);
+    if (entry && entry.kind === "entity") {
+      const currentName = entry.node.name;
+      if (currentName && currentName !== tokenName) {
+        rewrites.set(tokenName, currentName);
+      }
+    }
+  }
+  if (rewrites.size === 0) return trait;
+  const rename = (name) => rewrites.get(name);
+  const sm = trait.stateMachine;
+  const nextTransitions = sm?.transitions ? sm.transitions.map((t) => ({
+    ...t,
+    effects: t.effects ? renameEntityInEffects(
+      t.effects,
+      rename,
+      ID_ENTITY_PROPS
+    ) : t.effects
+  })) : sm?.transitions;
+  const nextTicks = trait.ticks ? trait.ticks.map((tick) => ({
+    ...tick,
+    effects: renameEntityInEffects(
+      tick.effects,
+      rename,
+      ID_ENTITY_PROPS
+    )
+  })) : trait.ticks;
+  const nextInitial = trait.initialEffects ? renameEntityInEffects(
+    trait.initialEffects,
+    rename,
+    ID_ENTITY_PROPS
+  ) : trait.initialEffects;
+  const nextLinked = trait.linkedEntity !== void 0 ? rewrites.get(trait.linkedEntity) ?? trait.linkedEntity : trait.linkedEntity;
+  refResolverLog.info("entity-ref:id-resolve", {
+    trait: trait.name,
+    rewrites: Object.fromEntries(rewrites)
+  });
+  return {
+    ...trait,
+    linkedEntity: nextLinked,
+    ...sm ? { stateMachine: { ...sm, transitions: nextTransitions ?? [] } } : {},
+    ...nextTicks !== void 0 ? { ticks: nextTicks } : {},
+    ...nextInitial !== void 0 ? { initialEffects: nextInitial } : {}
+  };
+}
+var REFERENCE_CONFIG_TYPE_TO_ID_KIND = {
+  entity: "entity",
+  trait: "trait",
+  event: "event"
+};
+function resolveConfigRefsById(trait, idIndex) {
+  const schema = trait.config;
+  if (!schema) return trait;
+  let nextSchema;
+  const rewrites = [];
+  for (const [key, field] of Object.entries(schema)) {
+    if (!field.refId || !isReferenceConfigType(field.type)) continue;
+    const expectedKind = REFERENCE_CONFIG_TYPE_TO_ID_KIND[field.type];
+    if (!expectedKind) continue;
+    const entry = idIndex.get(field.refId);
+    if (!entry || entry.kind !== expectedKind) continue;
+    const currentName = entry.kind === "entity" ? entry.node.name : entry.kind === "event" ? entry.node.key : entry.node.name;
+    if (!currentName || currentName === field.default) continue;
+    nextSchema ??= { ...schema };
+    nextSchema[key] = { ...field, default: currentName };
+    rewrites.push({ key, from: field.default, to: currentName });
+  }
+  if (!nextSchema) return trait;
+  refResolverLog.info("config-ref:id-resolve", {
+    trait: trait.name,
+    rewrites
+  });
+  return { ...trait, config: nextSchema };
+}
 function applyEventRenames(trait, renames) {
   if (!renames || Object.keys(renames).length === 0) return trait;
   const rename = (k) => k !== void 0 && k in renames ? renames[k] : k;
@@ -3678,17 +3935,24 @@ var ReferenceResolver = class {
   loader;
   options;
   localTraits;
+  /** id-keyed mirror of `localTraits`, populated wherever the trait carries an `id`. */
+  localTraitsById = /* @__PURE__ */ new Map();
   loaderInitialized = false;
   constructor(options) {
     this.options = options;
     this.loader = options.loader;
     this.localTraits = options.localTraits ?? /* @__PURE__ */ new Map();
+    for (const trait of this.localTraits.values()) {
+      if (trait.id) {
+        this.localTraitsById.set(trait.id, trait);
+      }
+    }
   }
   async ensureLoader() {
     if (this.loader || this.loaderInitialized) return;
     this.loaderInitialized = true;
     try {
-      const { ExternalOrbitalLoader } = await import('./external-loader-OPXVTNC4.js');
+      const { ExternalOrbitalLoader } = await import('./external-loader-FNK5AU6U.js');
       this.loader = new ExternalOrbitalLoader(this.options);
     } catch {
     }
@@ -3705,11 +3969,12 @@ var ReferenceResolver = class {
     } };
     const traitsList = orbital.traits ?? [];
     const alreadyResolved = traitsList.length > 0 && traitsList.every((t) => isInlineTrait(t));
-    const importsResult = alreadyResolved ? { success: true, data: { orbitals: /* @__PURE__ */ new Map() }} : await this.resolveImports(orbital.uses ?? [], sourcePath, importChain);
+    const importsResult = alreadyResolved ? { success: true, data: { orbitals: /* @__PURE__ */ new Map(), idIndex: /* @__PURE__ */ new Map() }} : await this.resolveImports(orbital.uses ?? [], sourcePath, importChain);
     if (!importsResult.success) {
       return { success: false, errors: importsResult.errors };
     }
     const imports = importsResult.data;
+    imports.idIndex = buildIdIndex(orbital, imports.orbitals);
     const entityResult = this.resolveEntity(orbital.entity, imports);
     if (!entityResult.success) {
       errors.push(...entityResult.errors);
@@ -3728,6 +3993,10 @@ var ReferenceResolver = class {
     if (!entityResult.success || !traitsResult.success || !pagesResult.success) {
       return { success: false, errors: ["Internal error: unexpected failure state"] };
     }
+    for (const resolvedTrait of traitsResult.data) {
+      resolvedTrait.trait = resolveEntityTokensById(resolvedTrait.trait, imports.idIndex);
+      resolvedTrait.trait = resolveConfigRefsById(resolvedTrait.trait, imports.idIndex);
+    }
     try {
       spliceLambdaTraitRefs(traitsResult.data, pagesResult.data);
     } catch (e) {
@@ -3759,7 +4028,7 @@ var ReferenceResolver = class {
     if (this.options.skipExternalLoading) {
       return {
         success: true,
-        data: { orbitals },
+        data: { orbitals, idIndex: /* @__PURE__ */ new Map() },
         warnings: ["External loading skipped"]
       };
     }
@@ -3793,7 +4062,7 @@ var ReferenceResolver = class {
     if (errors.length > 0) {
       return { success: false, errors };
     }
-    return { success: true, data: { orbitals }, warnings: [] };
+    return { success: true, data: { orbitals, idIndex: /* @__PURE__ */ new Map() }, warnings: [] };
   }
   /**
    * Resolve entity reference.
@@ -3924,7 +4193,8 @@ var ReferenceResolver = class {
         refObj.linkedEntity,
         refObj.name,
         refObj.events,
-        refObj.listens
+        refObj.listens,
+        refObj.refId
       );
     }
     if (typeof traitRef === "string") {
@@ -3938,7 +4208,7 @@ var ReferenceResolver = class {
   /**
    * Resolve a trait reference string.
    */
-  resolveTraitRefString(ref, imports, config, linkedEntity, overrideName, eventRenames, listensOverride) {
+  resolveTraitRefString(ref, imports, config, linkedEntity, overrideName, eventRenames, listensOverride, refId) {
     const parsed = parseImportedTraitRef(ref);
     if (parsed) {
       const imported = imports.orbitals.get(parsed.alias);
@@ -3950,7 +4220,7 @@ var ReferenceResolver = class {
           ]
         };
       }
-      const trait = this.findTraitInOrbital(imported.orbital, parsed.traitName);
+      const trait = this.findTraitInOrbital(imported.orbital, parsed.traitName, refId, imports.idIndex);
       if (!trait) {
         return {
           success: false,
@@ -3986,7 +4256,7 @@ var ReferenceResolver = class {
         warnings: []
       };
     }
-    const localTrait = this.localTraits.get(ref);
+    const localTrait = (refId && this.localTraitsById.get(refId)) ?? this.localTraits.get(ref);
     if (localTrait) {
       const baseLocal = overrideName ? { ...localTrait, name: overrideName } : localTrait;
       const { trait: configResolvedLocal, errors: localConfigRefErrors } = resolveConfigRefEmitNames(baseLocal, config);
@@ -4023,9 +4293,17 @@ var ReferenceResolver = class {
     };
   }
   /**
-   * Find a trait in an orbital by name.
+   * Find a trait in an orbital by name. Id-primary: when the calling ref
+   * carries a `refId` and the id index has a matching trait entry, return it
+   * directly — else fall back to the existing name match unchanged.
    */
-  findTraitInOrbital(orbital, traitName) {
+  findTraitInOrbital(orbital, traitName, refId, idIndex) {
+    if (refId && idIndex) {
+      const entry = idIndex.get(refId);
+      if (entry && entry.kind === "trait") {
+        return entry.node;
+      }
+    }
     for (const traitRef of orbital.traits) {
       if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
         if (traitRef.name === traitName) {
@@ -4099,7 +4377,7 @@ var ReferenceResolver = class {
   /**
    * Resolve a page reference string.
    */
-  resolvePageRefString(ref, imports) {
+  resolvePageRefString(ref, imports, refId) {
     const parsed = parsePageRef(ref);
     if (!parsed) {
       return {
@@ -4116,7 +4394,7 @@ var ReferenceResolver = class {
         ]
       };
     }
-    const page = this.findPageInOrbital(imported.orbital, parsed.pageName);
+    const page = this.findPageInOrbital(imported.orbital, parsed.pageName, refId, imports.idIndex);
     if (!page) {
       return {
         success: false,
@@ -4139,7 +4417,7 @@ var ReferenceResolver = class {
    * Resolve a page reference object with optional path override.
    */
   resolvePageRefObject(refObj, imports) {
-    const baseResult = this.resolvePageRefString(refObj.ref, imports);
+    const baseResult = this.resolvePageRefString(refObj.ref, imports, refObj.refId);
     if (!baseResult.success) {
       return baseResult;
     }
@@ -4160,9 +4438,17 @@ var ReferenceResolver = class {
     };
   }
   /**
-   * Find a page in an orbital by name.
+   * Find a page in an orbital by name. Id-primary: when the calling ref
+   * carries a `refId` and the id index has a matching page entry, return it
+   * directly — else fall back to the existing name match unchanged.
    */
-  findPageInOrbital(orbital, pageName) {
+  findPageInOrbital(orbital, pageName, refId, idIndex) {
+    if (refId && idIndex) {
+      const entry = idIndex.get(refId);
+      if (entry && entry.kind === "page") {
+        return { ...entry.node };
+      }
+    }
     const pages = orbital.pages;
     if (!pages) return null;
     for (const pageRef of pages) {
@@ -4195,6 +4481,9 @@ var ReferenceResolver = class {
   addLocalTraits(traits) {
     for (const trait of traits) {
       this.localTraits.set(trait.name, trait);
+      if (trait.id) {
+        this.localTraitsById.set(trait.id, trait);
+      }
     }
   }
   /**