@almadar/runtime 6.32.0 → 6.34.0

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

@@ -1,10 +1,12 @@
 import { parseCron, cronMinuteKey, cronMatches } from './chunk-OU3ITB5S.js';
+import { seedRandom, randomArrayElement, randomInt, shuffleArray, randomPastDate, randomBoolean, randomRecentDate, randomUuid, randomPhone, randomUrl, randomEmail, randomWords } from './chunk-OQJIK6PZ.js';
+import { collectTraitRefsFromValue, collectTraitRefsFromEffects } from './chunk-SCRAHWOC.js';
 import { createLogger, setNamespaceLevel } from '@almadar/logger';
-import { resolveBinding, evaluate, createMinimalContext, evaluateGuard, SExpressionEvaluator } from '@almadar/evaluator';
+import { createMinimalContext, resolveBinding, evaluate, evaluateGuard, SExpressionEvaluator } from '@almadar/evaluator';
 export { createMinimalContext } from '@almadar/evaluator';
 import { isKnownStdOperator } from '@almadar/std/registry';
-import { isCallSiteConfigDeclaration, OrbitalSchemaSchema, isInlineTrait, isEntityCall, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef } from '@almadar/core';
-import { faker } from '@faker-js/faker';
+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");
 var EventBus = class {
@@ -24,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;
@@ -35,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 {
@@ -289,6 +292,33 @@ var bindLog = createLogger("almadar:runtime:bindings");
 setNamespaceLevel("almadar:runtime:bindings", "WARN");
 var renderLog = createLogger("almadar:runtime:render-ui");
 var CLIENT_ONLY_BINDING_ROOTS = /* @__PURE__ */ new Set(["trait"]);
+var CALLSITE_PAYLOAD_PREFIX = "@callsitePayload.";
+function payloadValueToConfigValue(v) {
+  if (v === null || v === void 0) return null;
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  if (v instanceof Date) return v.toISOString();
+  if (Array.isArray(v)) return v.map(payloadValueToConfigValue);
+  if (typeof v === "object") {
+    const obj = {};
+    for (const [k, val] of Object.entries(v)) obj[k] = payloadValueToConfigValue(val);
+    return obj;
+  }
+  return String(v);
+}
+function resolveCallSitePayloadCaptures(config, payload) {
+  let ctx;
+  const out = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value === "string" && value.startsWith(CALLSITE_PAYLOAD_PREFIX)) {
+      const field = value.slice(CALLSITE_PAYLOAD_PREFIX.length);
+      if (!ctx) ctx = createMinimalContext({}, payload ?? {}, "idle");
+      out[key] = payloadValueToConfigValue(resolveBinding(`@payload.${field}`, ctx));
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
 function isClientOnlyBinding(value) {
   if (!value.startsWith("@")) return false;
   const afterAt = value.slice(1);
@@ -365,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)) {
@@ -373,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("@")) {
@@ -414,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];
@@ -497,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 "";
@@ -520,6 +575,7 @@ function processEvent(options) {
     traitState,
     trait,
     eventKey,
+    eventId,
     payload,
     entityData,
     config,
@@ -528,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 {
@@ -647,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
@@ -697,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`
@@ -715,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()]) {
@@ -802,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.
@@ -818,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) {
@@ -832,6 +968,7 @@ var StateMachineManager = class {
         traitState,
         trait,
         eventKey,
+        eventId,
         payload,
         entityData: perTraitEntity,
         config: this.traitConfigs.get(traitName),
@@ -873,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);
     }
   }
@@ -903,6 +1040,7 @@ var StateMachineManager = class {
         traitState,
         trait,
         eventKey: entry.eventKey,
+        eventId: entry.eventId,
         payload: entry.payload,
         entityData: perTraitEntity,
         config: this.traitConfigs.get(traitName),
@@ -982,7 +1120,7 @@ var StateMachineManager = class {
 
 // src/types.ts
 var HANDLER_MANIFEST = {
-  client: ["render-ui", "render", "navigate", "notify", "emit", "set", "log", "ref", "deref", "watch", "send-server"],
+  client: ["render-ui", "render", "navigate", "notify", "emit", "set", "log", "ref", "deref", "watch", "send-server", "browser/open-file-picker", "browser/clipboard-read", "browser/clipboard-write", "browser/geolocation-current"],
   server: ["persist", "fetch", "fetch-stream", "call-service", "emit", "set", "spawn", "despawn", "log", "ref", "deref", "swap!", "atomic", "os/watch-files", "os/watch-process", "os/watch-port", "os/watch-http", "os/watch-cron", "os/watch-signal", "os/watch-env", "os/debounce"],
   test: [
     "render-ui",
@@ -1002,7 +1140,11 @@ var HANDLER_MANIFEST = {
     "swap!",
     "watch",
     "atomic",
-    "send-server"
+    "send-server",
+    "browser/open-file-picker",
+    "browser/clipboard-read",
+    "browser/clipboard-write",
+    "browser/geolocation-current"
   ],
   ssr: ["render-ui", "render", "fetch", "emit", "set", "log", "ref", "deref"]
 };
@@ -1938,6 +2080,58 @@ var EffectExecutor = class _EffectExecutor {
         }, emitCfg);
         break;
       }
+      // === Browser device operators (client-side, user-gesture) ===
+      // Async host APIs routed to dedicated handler methods. Uniform
+      // `{ result }` / `{ error }` payload via runSubstrate. On the
+      // server (or any host without the API) the handler is absent →
+      // unsupported warning; a thrown error fires `emit.failure`.
+      case "browser/open-file-picker": {
+        const [positional, emitCfg] = this.splitSubstrateEmit(args);
+        const options = positional[0];
+        await this.runSubstrate(async () => {
+          if (!this.handlers.browserOpenFilePicker) {
+            this.logUnsupported("browser/open-file-picker");
+            return null;
+          }
+          return this.handlers.browserOpenFilePicker(options);
+        }, emitCfg);
+        break;
+      }
+      case "browser/clipboard-read": {
+        const [, emitCfg] = this.splitSubstrateEmit(args);
+        await this.runSubstrate(async () => {
+          if (!this.handlers.browserClipboardRead) {
+            this.logUnsupported("browser/clipboard-read");
+            return null;
+          }
+          return this.handlers.browserClipboardRead();
+        }, emitCfg);
+        break;
+      }
+      case "browser/clipboard-write": {
+        const [positional, emitCfg] = this.splitSubstrateEmit(args);
+        const text = positional[0];
+        await this.runSubstrate(async () => {
+          if (!this.handlers.browserClipboardWrite) {
+            this.logUnsupported("browser/clipboard-write");
+            return null;
+          }
+          return this.handlers.browserClipboardWrite(text);
+        }, emitCfg);
+        break;
+      }
+      case "browser/geolocation-current": {
+        const [positional, emitCfg] = this.splitSubstrateEmit(args);
+        const options = positional[0];
+        await this.runSubstrate(async () => {
+          if (!this.handlers.browserGeolocationCurrent) {
+            this.logUnsupported("browser/geolocation-current");
+            return null;
+          }
+          return this.handlers.browserGeolocationCurrent(options);
+        }, emitCfg);
+        break;
+      }
       default: {
         if (operator.includes("/")) {
           const [positional, emitCfg] = this.splitSubstrateEmit(args);
@@ -2104,21 +2298,6 @@ function collectDeclaredConfigDefaults(trait) {
   }
   return hasAny ? defaults : void 0;
 }
-function normalizeCallSiteConfigToValues(config) {
-  if (config === void 0) {
-    return void 0;
-  }
-  const out = {};
-  let hasAny = false;
-  for (const [key, entry] of Object.entries(config)) {
-    const value = isCallSiteConfigDeclaration(entry) ? entry.default : entry;
-    if (value !== void 0) {
-      out[key] = value;
-      hasAny = true;
-    }
-  }
-  return hasAny ? out : void 0;
-}
 function collectDeclaredEntityDefaults(entity) {
   if (!entity) return void 0;
   const defaults = {};
@@ -2134,7 +2313,7 @@ function collectDeclaredEntityDefaults(entity) {
 var mockLog = createLogger("almadar:runtime:mock");
 var DEFAULT_MOCK_SEED = 42;
 function picsumUrl(entityName, fieldName, width = 400, height = 400) {
-  const seed = `${entityName}-${fieldName}-${faker.number.int({ min: 0, max: 1e3 })}`;
+  const seed = `${entityName}-${fieldName}-${randomInt({ min: 0, max: 1e3 })}`;
   return `https://picsum.photos/seed/${encodeURIComponent(seed)}/${width}/${height}`;
 }
 var SEED_REFERENCE_TIMESTAMP = "2024-01-01T00:00:00.000Z";
@@ -2142,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 = {
@@ -2152,17 +2333,17 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
       // input doesn't overwrite the default.
       seed: config.seed ?? DEFAULT_MOCK_SEED
     };
-    faker.seed(this.config.seed);
+    seedRandom(this.config.seed);
     mockLog.debug("mock:adapter:init", { seed: this.config.seed });
   }
-  /** Re-anchor faker's PRNG to the configured seed. Called before every
+  /** Re-anchor the PRNG to the configured seed. Called before every
    *  re-seed loop so identical reseed sequences produce identical rows
-   *  (timestamps + faker-generated fields). Without this, the first
+   *  (timestamps + generated fields). Without this, the first
    *  reseed produces row set A, the second produces row set B, and
    *  diff observers see all rows as "changed" between frames. */
   resetFakerSeed() {
     if (this.config.seed !== void 0) {
-      faker.seed(this.config.seed);
+      seedRandom(this.config.seed);
     }
   }
   // ============================================================================
@@ -2188,11 +2369,14 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   /**
    * Register an entity schema and seed mock data.
    * If the schema has seedData, those instances are used directly.
-   * Otherwise, random mock data is generated with faker.
+   * Otherwise, random mock data is generated with the seeded PRNG.
    */
   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 {
@@ -2224,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;
@@ -2236,10 +2421,10 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
           if (eligible.length === 0) continue;
           const cardinality = field.relation.cardinality ?? "many";
           if (cardinality === "one" || cardinality === "many-to-one") {
-            row[field.name] = faker.helpers.arrayElement(eligible);
+            row[field.name] = randomArrayElement(eligible);
           } else {
-            const pickCount = Math.min(eligible.length, faker.number.int({ min: 2, max: 4 }));
-            row[field.name] = faker.helpers.shuffle(eligible.slice()).slice(0, pickCount);
+            const pickCount = Math.min(eligible.length, randomInt({ min: 2, max: 4 }));
+            row[field.name] = shuffleArray(eligible.slice()).slice(0, pickCount);
           }
         }
       }
@@ -2291,7 +2476,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
     const id = this.nextId(entityName);
     const item = {
       id,
-      createdAt: faker.date.past({ years: 1 }).toISOString(),
+      createdAt: randomPastDate({ years: 1 }).toISOString(),
       updatedAt: SEED_REFERENCE_TIMESTAMP
     };
     for (const field of fields) {
@@ -2333,16 +2518,16 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
       case "string":
         return this.generateStringValue(entityName, field, index);
       case "number":
-        return faker.number.int({ min: 0, max: 100 });
+        return randomInt({ min: 0, max: 100 });
       case "boolean":
-        return faker.datatype.boolean();
+        return randomBoolean();
       case "date":
       case "timestamp":
       case "datetime":
         return this.generateDateValue(field);
       case "enum":
         if (field.values && field.values.length > 0) {
-          return faker.helpers.arrayElement(field.values);
+          return randomArrayElement(field.values);
         }
         return null;
       case "relation":
@@ -2367,7 +2552,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   generateArrayValue(entityName, field, index, depth = 0) {
     if (field.type !== "array" || !field.items) return [];
     if (depth >= _MockPersistenceAdapter.MAX_NESTED_DEPTH) return [];
-    const count = faker.number.int({ min: 3, max: 5 });
+    const count = randomInt({ min: 3, max: 5 });
     const out = [];
     const elementName = field.name ?? "item";
     for (let i = 0; i < count; i++) {
@@ -2381,7 +2566,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   }
   /**
    * Generate a single object value with each declared property populated
-   * by faker. Walks `properties` and recursively delegates to
+   * by the seeded PRNG. Walks `properties` and recursively delegates to
    * `generateFieldValue` per property so nested objects-of-arrays-of-objects
    * compose correctly.
    */
@@ -2398,29 +2583,29 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   /**
    * Generate a string value based on the field's declared schema metadata.
    * Reads `values` (enum) first, then `format` (email/url/phone/uuid/date/
-   * datetime), then falls back to faker.lorem.words. No field-name heuristics
+   * datetime), then falls back to randomWords. No field-name heuristics
    * — the schema is the source of truth. If a caller needs a real email, they
    * declare `format: "email"`; if they need an enum, they declare `values: [...]`.
    */
   generateStringValue(entityName, field, _index) {
     const values = "values" in field ? field.values : void 0;
     if (values && values.length > 0) {
-      return faker.helpers.arrayElement(values);
+      return randomArrayElement(values);
     }
     const fieldName = field.name ?? "field";
     switch (field.format) {
       case "email":
-        return faker.internet.email();
+        return randomEmail();
       case "url":
-        return faker.internet.url();
+        return randomUrl();
       case "phone":
-        return faker.phone.number();
+        return randomPhone();
       case "uuid":
-        return faker.string.uuid();
+        return randomUuid();
       case "date":
-        return faker.date.recent().toISOString().split("T")[0];
+        return randomRecentDate().toISOString().split("T")[0];
       case "datetime":
-        return faker.date.recent().toISOString();
+        return randomRecentDate().toISOString();
       case "image":
       case "avatar":
       case "thumbnail":
@@ -2430,7 +2615,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
     if (lname === "image" || lname === "imageurl" || lname === "image_url" || lname === "photo" || lname === "photourl" || lname === "photo_url" || lname === "avatar" || lname === "avatarurl" || lname === "avatar_url" || lname === "thumbnail" || lname === "thumbnailurl" || lname === "thumbnail_url" || lname === "picture" || lname === "pictureurl" || lname === "cover" || lname === "coverurl" || lname === "banner" || lname === "bannerurl") {
       return picsumUrl(entityName, fieldName);
     }
-    const value = faker.lorem.words(2);
+    const value = randomWords(2);
     mockLog.debug("field:fallback-lorem", () => ({
       entityName,
       fieldName: field.name,
@@ -2446,7 +2631,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
    * field-name heuristics.
    */
   generateDateValue(field) {
-    const date = faker.date.recent({ days: 30 });
+    const date = randomRecentDate({ days: 30 });
     if (field.format === "date") return date.toISOString().split("T")[0];
     return date.toISOString();
   }
@@ -2530,7 +2715,7 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
     this.stores.delete(normalized);
     this.idCounters.delete(normalized);
   }
-  /** Clear all data + re-anchor faker so the next seed loop reproduces
+  /** Clear all data + re-anchor the PRNG so the next seed loop reproduces
    *  identical rows. Hermetic-frame mode calls this between every step
    *  via OrbitalServerRuntime.resetMockPersistence. */
   clearAll() {
@@ -2902,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;
@@ -3158,7 +3343,310 @@ function createUnifiedLoader(options) {
   return new UnifiedLoader(options);
 }
 createLogger("almadar:runtime:studio-config");
+
+// src/ui/splice-lambda-traits.ts
+var TRAIT_BINDING_PREFIX = "@trait.";
+var CONFIG_BINDING_PREFIX = "@config.";
+var LambdaSpliceError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "LambdaSpliceError";
+  }
+  code;
+};
+function isRenderUiEffect(effect) {
+  return Array.isArray(effect) && effect.length >= 1 && effect[0] === "render-ui";
+}
+function renderOnlyTemplate(trait) {
+  if (trait.listens && trait.listens.length > 0) return null;
+  if (trait.ticks && trait.ticks.length > 0) return null;
+  const sm = trait.stateMachine;
+  const states = sm?.states ?? [];
+  if (states.length > 1) return null;
+  let template = null;
+  for (const transition of sm?.transitions ?? []) {
+    const selfLoop = transition.from === transition.to;
+    const guarded = transition.guard !== void 0 && transition.guard !== null;
+    if (!selfLoop || guarded) return null;
+    for (const effect of transition.effects ?? []) {
+      if (!isRenderUiEffect(effect) || !Array.isArray(effect)) return null;
+      const pattern = effect[2];
+      if (pattern === void 0) return null;
+      if (template !== null) return null;
+      template = pattern;
+    }
+  }
+  return template;
+}
+function resolveObjectPath(value, path) {
+  let cur = value;
+  for (const seg of path.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[seg];
+    if (cur === void 0) return void 0;
+  }
+  return cur;
+}
+function substituteConfig(expr, subs) {
+  if (typeof expr === "string") {
+    if (!expr.startsWith(CONFIG_BINDING_PREFIX)) return expr;
+    const rest = expr.slice(CONFIG_BINDING_PREFIX.length);
+    const dot = rest.indexOf(".");
+    const param = dot === -1 ? rest : rest.slice(0, dot);
+    const trailing = dot === -1 ? void 0 : rest.slice(dot + 1);
+    if (!(param in subs)) return expr;
+    const value = subs[param];
+    if (trailing === void 0) {
+      if (typeof value === "string" && value === expr) return expr;
+      return substituteConfig(value, subs);
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const leaf = resolveObjectPath(value, trailing);
+      if (leaf !== void 0) return substituteConfig(leaf, subs);
+    }
+    return expr;
+  }
+  if (Array.isArray(expr)) {
+    return expr.map((item) => substituteConfig(item, subs));
+  }
+  if (expr !== null && typeof expr === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(expr)) {
+      out[k] = substituteConfig(v, subs);
+    }
+    return out;
+  }
+  return expr;
+}
+function buildTemplate(trait) {
+  const raw = renderOnlyTemplate(trait);
+  const emits = trait.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, traitName: trait.name, id: trait.id, embedIds: trait.traitEmbedIds };
+}
+function isLambdaForm(expr) {
+  return expr.length === 3 && (expr[0] === "fn" || expr[0] === "lambda");
+}
+function spliceExpr(expr, inLambda, st) {
+  if (typeof expr === "string") {
+    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 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(
+        "LAMBDA_STATEFUL_TRAIT",
+        `Trait "${name}" keeps its own state machine and cannot be expanded per list item \u2014 use the list pattern's item events (referenced inside a lambda in trait "${st.hostName}")`
+      );
+    }
+    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([entry.traitName, emit]);
+    st.spliced.add(entry.traitName);
+    st.changed = true;
+    return expanded;
+  }
+  if (Array.isArray(expr)) {
+    if (isLambdaForm(expr)) {
+      return [expr[0], expr[1], spliceExpr(expr[2], true, st)];
+    }
+    return expr.map((item) => spliceExpr(item, inLambda, st));
+  }
+  if (expr !== null && typeof expr === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(expr)) {
+      out[k] = spliceExpr(v, inLambda, st);
+    }
+    return out;
+  }
+  return expr;
+}
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonical(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function mergeWrapperEmits(host, incoming) {
+  const emits = [...host.emits ?? []];
+  for (const [wrapper, emit] of incoming) {
+    const existing = emits.find((e) => e.event === emit.event);
+    if (existing) {
+      const same = JSON.stringify(canonical(existing)) === JSON.stringify(canonical(emit));
+      if (!same) {
+        throw new LambdaSpliceError(
+          "EMIT_MERGE_CONFLICT",
+          `Emit "${emit.event}" merged from spliced wrapper "${wrapper}" conflicts with an existing "${emit.event}" on host "${host.name}" (different payload shape)`
+        );
+      }
+    } else {
+      emits.push(emit);
+    }
+  }
+  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, rawTokens);
+        }
+        collectTraitRefsFromEffects(t.effects, rawTokens);
+      }
+      for (const tick of trait.ticks ?? []) {
+        if (tick.guard !== void 0 && tick.guard !== null) {
+          collectTraitRefsFromValue(tick.guard, rawTokens);
+        }
+        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, 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) {
+      if (spliced.has(trait.name) && !stillReferenced.has(trait.name)) {
+        removable.add(trait.name);
+      }
+    }
+    if (removable.size === 0) return;
+    for (const { page } of pages) {
+      const pageTraits = page.traits;
+      if (!pageTraits) continue;
+      const survivors2 = pageTraits.filter((pt) => !removable.has(pt.ref)).length;
+      if (survivors2 === 0) {
+        for (const pt of pageTraits) removable.delete(pt.ref);
+      }
+    }
+    if (removable.size === 0) return;
+    for (const resolvedPage of pages) {
+      const pageTraits = resolvedPage.page.traits;
+      if (pageTraits) {
+        resolvedPage.page.traits = pageTraits.filter((pt) => !removable.has(pt.ref));
+      }
+    }
+    const survivors = traits.filter(({ trait }) => !removable.has(trait.name));
+    traits.length = 0;
+    traits.push(...survivors);
+  }
+}
+function spliceLambdaTraitRefs(traits, pages) {
+  if (traits.length === 0) return;
+  const templates = /* @__PURE__ */ new Map();
+  const templatesById = /* @__PURE__ */ new Map();
+  for (const { trait } of traits) {
+    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: [],
+      spliced,
+      hostName: host.name,
+      changed: false
+    };
+    const sm = host.stateMachine;
+    const nextTransitions = sm?.transitions ? sm.transitions.map((t) => ({
+      ...t,
+      effects: t.effects ? t.effects.map((e) => spliceExpr(e, false, st)) : t.effects
+    })) : sm?.transitions;
+    const nextTicks = host.ticks ? host.ticks.map((tick) => ({
+      ...tick,
+      effects: tick.effects.map((e) => spliceExpr(e, false, st))
+    })) : host.ticks;
+    if (!st.changed) {
+      continue;
+    }
+    const nextEmits = st.merged.length > 0 ? mergeWrapperEmits(host, st.merged) : host.emits;
+    resolved.trait = {
+      ...host,
+      ...sm ? { stateMachine: { ...sm, transitions: nextTransitions ?? [] } } : {},
+      ...nextTicks !== void 0 ? { ticks: nextTicks } : {},
+      ...nextEmits !== void 0 ? { emits: nextEmits } : {}
+    };
+  }
+  if (spliced.size > 0) {
+    removeConsumedWrappers(traits, pages, spliced);
+  }
+}
+
+// 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)) {
@@ -3208,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([
@@ -3245,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);
@@ -3267,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;
     });
@@ -3279,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 };
   });
@@ -3299,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;
@@ -3329,21 +3904,55 @@ function applyEventRenames(trait, renames) {
     emits: nextEmits
   };
 }
+function resolveConfigRefEmitNames(trait, callSiteConfig) {
+  const emits = trait.emits ?? [];
+  const hasRef = emits.some((em) => configRefEventKnob(em.event) !== void 0);
+  if (!hasRef) return { trait, errors: [] };
+  const effectiveConfig = {
+    ...normalizeCallSiteConfigToValues(trait.config) ?? {},
+    ...normalizeCallSiteConfigToValues(callSiteConfig) ?? {}
+  };
+  const errors = [];
+  const nextEmits = emits.map((em) => {
+    if (configRefEventKnob(em.event) === void 0) return em;
+    const result = resolveConfigRefEventName(em.event, trait.config, effectiveConfig);
+    if (!result.ok) {
+      errors.push(
+        `Trait "${trait.name}" emits \`${em.event}\` but the reference is invalid (${result.error}): the knob must be a declared string-typed config field with a default.`
+      );
+      return em;
+    }
+    refResolverLog.debug("emit-config-ref:resolved", {
+      trait: trait.name,
+      ref: em.event,
+      resolved: result.value
+    });
+    return { ...em, event: result.value };
+  });
+  return { trait: { ...trait, emits: nextEmits }, errors };
+}
 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 {
     }
@@ -3360,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);
@@ -3383,6 +3993,18 @@ 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) {
+      if (e instanceof LambdaSpliceError) {
+        return { success: false, errors: [e.message] };
+      }
+      throw e;
+    }
     return {
       success: true,
       data: {
@@ -3406,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"]
       };
     }
@@ -3440,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.
@@ -3549,10 +4171,14 @@ var ReferenceResolver = class {
    */
   resolveTraitRef(traitRef, imports) {
     if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+      const { trait: resolvedInline, errors } = resolveConfigRefEmitNames(traitRef);
+      if (errors.length > 0) {
+        return { success: false, errors };
+      }
       return {
         success: true,
         data: {
-          trait: traitRef,
+          trait: resolvedInline,
           source: { type: "inline" }
         },
         warnings: []
@@ -3567,7 +4193,8 @@ var ReferenceResolver = class {
         refObj.linkedEntity,
         refObj.name,
         refObj.events,
-        refObj.listens
+        refObj.listens,
+        refObj.refId
       );
     }
     if (typeof traitRef === "string") {
@@ -3581,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);
@@ -3593,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,
@@ -3603,7 +4230,11 @@ var ReferenceResolver = class {
         };
       }
       const baseTrait = overrideName ? { ...trait, name: overrideName } : trait;
-      const reboundTrait = applyLinkedEntityRename(baseTrait, linkedEntity);
+      const { trait: configResolvedTrait, errors: configRefErrors } = resolveConfigRefEmitNames(baseTrait, config);
+      if (configRefErrors.length > 0) {
+        return { success: false, errors: configRefErrors };
+      }
+      const reboundTrait = applyLinkedEntityRename(configResolvedTrait, linkedEntity);
       const renamedTrait = applyEventRenames(reboundTrait, eventRenames);
       const finalTrait = listensOverride !== void 0 ? { ...renamedTrait, listens: listensOverride } : renamedTrait;
       if (listensOverride !== void 0) {
@@ -3625,10 +4256,14 @@ 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 reboundLocal = applyLinkedEntityRename(baseLocal, linkedEntity);
+      const { trait: configResolvedLocal, errors: localConfigRefErrors } = resolveConfigRefEmitNames(baseLocal, config);
+      if (localConfigRefErrors.length > 0) {
+        return { success: false, errors: localConfigRefErrors };
+      }
+      const reboundLocal = applyLinkedEntityRename(configResolvedLocal, linkedEntity);
       const renamedLocalTrait = applyEventRenames(reboundLocal, eventRenames);
       const finalLocalTrait = listensOverride !== void 0 ? { ...renamedLocalTrait, listens: listensOverride } : renamedLocalTrait;
       if (listensOverride !== void 0) {
@@ -3658,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) {
@@ -3734,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 {
@@ -3751,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,
@@ -3774,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;
     }
@@ -3795,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) {
@@ -3830,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);
+      }
     }
   }
   /**
@@ -4052,4 +4706,4 @@ var InMemoryPersistence = class {
   }
 };
 
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, containsBindings, createContextFromBindings, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, extractBindings, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeCallSiteConfigToValues, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes };
+export { CALLSITE_PAYLOAD_PREFIX, EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, containsBindings, createContextFromBindings, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, extractBindings, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, resolveCallSitePayloadCaptures, validateEventPayload, validatePayloadShapes };