@almadar/runtime 1.0.0

package/dist/OrbitalServerRuntime.js

@@ -0,0 +1,3185 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { OrbitalSchemaSchema, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef } from '@almadar/core';
+import { Router } from 'express';
+import { evaluateGuard, createMinimalContext, resolveBinding, evaluate } from '@almadar/evaluator';
+import { faker } from '@faker-js/faker';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/loader/external-loader.ts
+var external_loader_exports = {};
+__export(external_loader_exports, {
+  ExternalOrbitalLoader: () => ExternalOrbitalLoader,
+  ImportChain: () => ImportChain,
+  LoaderCache: () => LoaderCache,
+  createLoader: () => createLoader,
+  parseImportPath: () => parseImportPath
+});
+function createLoader(basePath, options) {
+  return new ExternalOrbitalLoader({
+    basePath,
+    ...options
+  });
+}
+function parseImportPath(importPath) {
+  const hashIndex = importPath.indexOf("#");
+  if (hashIndex === -1) {
+    return { path: importPath };
+  }
+  return {
+    path: importPath.slice(0, hashIndex),
+    fragment: importPath.slice(hashIndex + 1)
+  };
+}
+var ImportChain, LoaderCache, ExternalOrbitalLoader;
+var init_external_loader = __esm({
+  "src/loader/external-loader.ts"() {
+    ImportChain = class _ImportChain {
+      chain = [];
+      /**
+       * Try to add a path to the chain.
+       * @returns Error message if circular, null if OK
+       */
+      push(absolutePath) {
+        if (this.chain.includes(absolutePath)) {
+          const cycle = [...this.chain.slice(this.chain.indexOf(absolutePath)), absolutePath];
+          return `Circular import detected: ${cycle.join(" -> ")}`;
+        }
+        this.chain.push(absolutePath);
+        return null;
+      }
+      /**
+       * Remove the last path from the chain.
+       */
+      pop() {
+        this.chain.pop();
+      }
+      /**
+       * Clone the chain for nested loading.
+       */
+      clone() {
+        const newChain = new _ImportChain();
+        newChain.chain = [...this.chain];
+        return newChain;
+      }
+    };
+    LoaderCache = class {
+      cache = /* @__PURE__ */ new Map();
+      get(absolutePath) {
+        return this.cache.get(absolutePath);
+      }
+      set(absolutePath, schema) {
+        this.cache.set(absolutePath, schema);
+      }
+      has(absolutePath) {
+        return this.cache.has(absolutePath);
+      }
+      clear() {
+        this.cache.clear();
+      }
+      get size() {
+        return this.cache.size;
+      }
+    };
+    ExternalOrbitalLoader = class {
+      options;
+      cache;
+      constructor(options) {
+        this.options = {
+          stdLibPath: options.stdLibPath ?? "",
+          scopedPaths: options.scopedPaths ?? {},
+          allowOutsideBasePath: options.allowOutsideBasePath ?? false,
+          ...options
+        };
+        this.cache = new LoaderCache();
+      }
+      /**
+       * Load a schema from an import path.
+       *
+       * @param importPath - The import path (e.g., "./health.orb", "std/behaviors/game-core")
+       * @param fromPath - The path of the file doing the import (for relative resolution)
+       * @param chain - Import chain for circular detection
+       */
+      async load(importPath, fromPath, chain) {
+        const importChain = chain ?? new ImportChain();
+        const resolveResult = this.resolvePath(importPath, fromPath);
+        if (!resolveResult.success) {
+          return resolveResult;
+        }
+        const absolutePath = resolveResult.data;
+        const circularError = importChain.push(absolutePath);
+        if (circularError) {
+          return { success: false, error: circularError };
+        }
+        try {
+          const cached = this.cache.get(absolutePath);
+          if (cached) {
+            return { success: true, data: cached };
+          }
+          const loadResult = await this.loadFile(absolutePath);
+          if (!loadResult.success) {
+            return loadResult;
+          }
+          const loaded = {
+            schema: loadResult.data,
+            sourcePath: absolutePath,
+            importPath
+          };
+          this.cache.set(absolutePath, loaded);
+          return { success: true, data: loaded };
+        } finally {
+          importChain.pop();
+        }
+      }
+      /**
+       * Load a specific orbital from a schema by name.
+       *
+       * @param importPath - The import path
+       * @param orbitalName - The orbital name (optional, defaults to first orbital)
+       * @param fromPath - The path of the file doing the import
+       * @param chain - Import chain for circular detection
+       */
+      async loadOrbital(importPath, orbitalName, fromPath, chain) {
+        const schemaResult = await this.load(importPath, fromPath, chain);
+        if (!schemaResult.success) {
+          return schemaResult;
+        }
+        const schema = schemaResult.data.schema;
+        let orbital;
+        if (orbitalName) {
+          const found = schema.orbitals.find((o) => o.name === orbitalName);
+          if (!found) {
+            return {
+              success: false,
+              error: `Orbital "${orbitalName}" not found in ${importPath}. Available: ${schema.orbitals.map((o) => o.name).join(", ")}`
+            };
+          }
+          orbital = found;
+        } else {
+          if (schema.orbitals.length === 0) {
+            return {
+              success: false,
+              error: `No orbitals found in ${importPath}`
+            };
+          }
+          orbital = schema.orbitals[0];
+        }
+        return {
+          success: true,
+          data: {
+            orbital,
+            sourcePath: schemaResult.data.sourcePath,
+            importPath
+          }
+        };
+      }
+      /**
+       * Resolve an import path to an absolute filesystem path.
+       */
+      resolvePath(importPath, fromPath) {
+        if (importPath.startsWith("std/")) {
+          return this.resolveStdPath(importPath);
+        }
+        if (importPath.startsWith("@")) {
+          return this.resolveScopedPath(importPath);
+        }
+        if (importPath.startsWith("./") || importPath.startsWith("../")) {
+          return this.resolveRelativePath(importPath, fromPath);
+        }
+        if (path.isAbsolute(importPath)) {
+          if (!this.options.allowOutsideBasePath) {
+            return {
+              success: false,
+              error: `Absolute paths not allowed: ${importPath}`
+            };
+          }
+          return { success: true, data: importPath };
+        }
+        return this.resolveRelativePath(`./${importPath}`, fromPath);
+      }
+      /**
+       * Resolve a standard library path.
+       */
+      resolveStdPath(importPath) {
+        if (!this.options.stdLibPath) {
+          return {
+            success: false,
+            error: `Standard library path not configured. Cannot load: ${importPath}`
+          };
+        }
+        const relativePath = importPath.slice(4);
+        let absolutePath = path.join(this.options.stdLibPath, relativePath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        const normalizedPath = path.normalize(absolutePath);
+        const normalizedStdLib = path.normalize(this.options.stdLibPath);
+        if (!normalizedPath.startsWith(normalizedStdLib)) {
+          return {
+            success: false,
+            error: `Path traversal outside std library: ${importPath}`
+          };
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Resolve a scoped package path.
+       */
+      resolveScopedPath(importPath) {
+        const match = importPath.match(/^(@[^/]+)/);
+        if (!match) {
+          return {
+            success: false,
+            error: `Invalid scoped package path: ${importPath}`
+          };
+        }
+        const scope = match[1];
+        const scopeRoot = this.options.scopedPaths[scope];
+        if (!scopeRoot) {
+          return {
+            success: false,
+            error: `Scoped package "${scope}" not configured. Available: ${Object.keys(this.options.scopedPaths).join(", ") || "none"}`
+          };
+        }
+        const relativePath = importPath.slice(scope.length + 1);
+        let absolutePath = path.join(scopeRoot, relativePath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        const normalizedPath = path.normalize(absolutePath);
+        const normalizedRoot = path.normalize(scopeRoot);
+        if (!normalizedPath.startsWith(normalizedRoot)) {
+          return {
+            success: false,
+            error: `Path traversal outside scoped package: ${importPath}`
+          };
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Resolve a relative path.
+       */
+      resolveRelativePath(importPath, fromPath) {
+        const baseDir = fromPath ? path.dirname(fromPath) : this.options.basePath;
+        let absolutePath = path.resolve(baseDir, importPath);
+        if (!absolutePath.endsWith(".orb")) {
+          absolutePath += ".orb";
+        }
+        if (!this.options.allowOutsideBasePath) {
+          const normalizedPath = path.normalize(absolutePath);
+          const normalizedBase = path.normalize(this.options.basePath);
+          if (!normalizedPath.startsWith(normalizedBase)) {
+            return {
+              success: false,
+              error: `Path traversal outside base path: ${importPath}. Base: ${this.options.basePath}`
+            };
+          }
+        }
+        return { success: true, data: absolutePath };
+      }
+      /**
+       * Load and parse an .orb file.
+       */
+      async loadFile(absolutePath) {
+        try {
+          if (!fs.existsSync(absolutePath)) {
+            return {
+              success: false,
+              error: `File not found: ${absolutePath}`
+            };
+          }
+          const content = await fs.promises.readFile(absolutePath, "utf-8");
+          let data;
+          try {
+            data = JSON.parse(content);
+          } catch (e) {
+            return {
+              success: false,
+              error: `Invalid JSON in ${absolutePath}: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          const parseResult = OrbitalSchemaSchema.safeParse(data);
+          if (!parseResult.success) {
+            const errors = parseResult.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+            return {
+              success: false,
+              error: `Invalid schema in ${absolutePath}:
+${errors}`
+            };
+          }
+          return { success: true, data: parseResult.data };
+        } catch (e) {
+          return {
+            success: false,
+            error: `Failed to load ${absolutePath}: ${e instanceof Error ? e.message : String(e)}`
+          };
+        }
+      }
+      /**
+       * Clear the cache.
+       */
+      clearCache() {
+        this.cache.clear();
+      }
+      /**
+       * Get cache statistics.
+       */
+      getCacheStats() {
+        return { size: this.cache.size };
+      }
+    };
+  }
+});
+
+// src/EventBus.ts
+var EventBus = class {
+  listeners = /* @__PURE__ */ new Map();
+  debug;
+  constructor(options = {}) {
+    this.debug = options.debug ?? false;
+  }
+  /**
+   * Emit an event to all registered listeners
+   */
+  emit(type, payload, source) {
+    const event = {
+      type,
+      payload,
+      timestamp: Date.now(),
+      source
+    };
+    const listeners = this.listeners.get(type);
+    const listenerCount = listeners?.size ?? 0;
+    if (this.debug) {
+      if (listenerCount > 0) {
+        console.log(`[EventBus] Emit: ${type} \u2192 ${listenerCount} listener(s)`, payload);
+      } else {
+        console.warn(`[EventBus] Emit: ${type} (NO LISTENERS)`, payload);
+      }
+    }
+    if (listeners) {
+      const listenersCopy = Array.from(listeners);
+      for (const listener of listenersCopy) {
+        try {
+          listener(event);
+        } catch (error) {
+          console.error(`[EventBus] Error in listener for '${type}':`, error);
+        }
+      }
+    }
+    if (type !== "*") {
+      const wildcardListeners = this.listeners.get("*");
+      if (wildcardListeners) {
+        for (const listener of Array.from(wildcardListeners)) {
+          try {
+            listener(event);
+          } catch (error) {
+            console.error(`[EventBus] Error in wildcard listener:`, error);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Subscribe to an event type
+   */
+  on(type, listener) {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, /* @__PURE__ */ new Set());
+    }
+    const listeners = this.listeners.get(type);
+    listeners.add(listener);
+    if (this.debug) {
+      console.log(`[EventBus] Subscribed to '${type}', total: ${listeners.size}`);
+    }
+    return () => {
+      listeners.delete(listener);
+      if (this.debug) {
+        console.log(`[EventBus] Unsubscribed from '${type}', remaining: ${listeners.size}`);
+      }
+      if (listeners.size === 0) {
+        this.listeners.delete(type);
+      }
+    };
+  }
+  /**
+   * Subscribe to ALL events (wildcard listener)
+   * Useful for event tracking, logging, debugging
+   */
+  onAny(listener) {
+    return this.on("*", listener);
+  }
+  /**
+   * Check if there are listeners for an event type
+   */
+  hasListeners(type) {
+    const listeners = this.listeners.get(type);
+    return listeners !== void 0 && listeners.size > 0;
+  }
+  /**
+   * Get all registered event types
+   */
+  getRegisteredEvents() {
+    return Array.from(this.listeners.keys());
+  }
+  /**
+   * Clear all listeners
+   */
+  clear() {
+    if (this.debug) {
+      console.log(`[EventBus] Clearing all listeners (${this.listeners.size} event types)`);
+    }
+    this.listeners.clear();
+  }
+  /**
+   * Get listener count for an event type (for testing)
+   */
+  getListenerCount(type) {
+    return this.listeners.get(type)?.size ?? 0;
+  }
+};
+var OPERATORS = /* @__PURE__ */ new Set([
+  // Comparison
+  "=",
+  "!=",
+  "<",
+  ">",
+  "<=",
+  ">=",
+  // Logic
+  "and",
+  "or",
+  "not",
+  "if",
+  // Math
+  "+",
+  "-",
+  "*",
+  "/",
+  "%",
+  // Array
+  "count",
+  "first",
+  "last",
+  "map",
+  "filter",
+  "find",
+  "some",
+  "every",
+  "reduce",
+  // String
+  "concat",
+  "upper",
+  "lower",
+  "trim",
+  "substring",
+  "split",
+  "join",
+  "str",
+  // Effects
+  "set",
+  "emit",
+  "navigate",
+  "persist",
+  "notify",
+  "render-ui",
+  "render",
+  "spawn",
+  "despawn",
+  "call-service",
+  "do",
+  "when",
+  "increment",
+  "decrement",
+  "log"
+]);
+function interpolateProps(props, ctx) {
+  const result = {};
+  for (const [key, value] of Object.entries(props)) {
+    result[key] = interpolateValue(value, ctx);
+  }
+  return result;
+}
+function interpolateValue(value, ctx) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return interpolateString(value, ctx);
+  }
+  if (Array.isArray(value)) {
+    return interpolateArray(value, ctx);
+  }
+  if (typeof value === "object") {
+    return interpolateProps(value, ctx);
+  }
+  return value;
+}
+function interpolateString(value, ctx) {
+  if (value.startsWith("@") && isPureBinding(value)) {
+    return resolveBinding(value, ctx);
+  }
+  if (value.includes("@")) {
+    return interpolateEmbeddedBindings(value, ctx);
+  }
+  return value;
+}
+function isPureBinding(value) {
+  return /^@[\w]+(?:\.[\w]+)*$/.test(value);
+}
+function interpolateEmbeddedBindings(value, ctx) {
+  return value.replace(/@[\w]+(?:\.[\w]+)*/g, (match) => {
+    const resolved = resolveBinding(match, ctx);
+    return resolved !== void 0 ? String(resolved) : match;
+  });
+}
+function interpolateArray(value, ctx) {
+  if (value.length === 0) {
+    return [];
+  }
+  if (isSExpression(value)) {
+    return evaluate(value, ctx);
+  }
+  return value.map((item) => interpolateValue(item, ctx));
+}
+function isSExpression(value) {
+  if (value.length === 0) return false;
+  const first = value[0];
+  if (typeof first !== "string") return false;
+  if (OPERATORS.has(first)) return true;
+  if (first.includes("/")) return true;
+  if (first === "lambda" || first === "let") return true;
+  return false;
+}
+function createContextFromBindings(bindings) {
+  return createMinimalContext(
+    bindings.entity || {},
+    bindings.payload || {},
+    bindings.state || "idle"
+  );
+}
+function findInitialState(trait) {
+  if (!trait.states || trait.states.length === 0) {
+    console.warn(`[StateMachine] Trait "${trait.name}" has no states defined, using "unknown"`);
+    return "unknown";
+  }
+  const markedInitial = trait.states.find((s) => s.isInitial)?.name;
+  const firstState = trait.states[0]?.name;
+  return markedInitial || firstState || "unknown";
+}
+function createInitialTraitState(trait) {
+  return {
+    traitName: trait.name,
+    currentState: findInitialState(trait),
+    previousState: null,
+    lastEvent: null,
+    context: {}
+  };
+}
+function findTransition(trait, currentState, eventKey) {
+  if (!trait.transitions || trait.transitions.length === 0) {
+    return void 0;
+  }
+  return trait.transitions.find((t) => {
+    if (Array.isArray(t.from)) {
+      return t.from.includes(currentState) && t.event === eventKey;
+    }
+    return t.from === currentState && t.event === eventKey;
+  });
+}
+function normalizeEventKey(eventKey) {
+  return eventKey.startsWith("UI:") ? eventKey.slice(3) : eventKey;
+}
+function processEvent(options) {
+  const { traitState, trait, eventKey, payload, entityData } = options;
+  const normalizedEvent = normalizeEventKey(eventKey);
+  const transition = findTransition(trait, traitState.currentState, normalizedEvent);
+  if (!transition) {
+    return {
+      executed: false,
+      newState: traitState.currentState,
+      previousState: traitState.currentState,
+      effects: []
+    };
+  }
+  if (transition.guard) {
+    const ctx = createContextFromBindings({
+      entity: entityData,
+      payload,
+      state: traitState.currentState
+    });
+    try {
+      const guardPasses = evaluateGuard(
+        transition.guard,
+        ctx
+      );
+      if (!guardPasses) {
+        return {
+          executed: false,
+          newState: traitState.currentState,
+          previousState: traitState.currentState,
+          effects: [],
+          transition: {
+            from: traitState.currentState,
+            to: transition.to,
+            event: normalizedEvent
+          },
+          guardResult: false
+        };
+      }
+    } catch (error) {
+      console.error("[StateMachineCore] Guard evaluation error:", error);
+    }
+  }
+  return {
+    executed: true,
+    newState: transition.to,
+    previousState: traitState.currentState,
+    effects: transition.effects || [],
+    transition: {
+      from: traitState.currentState,
+      to: transition.to,
+      event: normalizedEvent
+    },
+    guardResult: transition.guard ? true : void 0
+  };
+}
+var StateMachineManager = class {
+  traits = /* @__PURE__ */ new Map();
+  states = /* @__PURE__ */ new Map();
+  constructor(traits = []) {
+    for (const trait of traits) {
+      this.addTrait(trait);
+    }
+  }
+  /**
+   * Add a trait to the manager.
+   */
+  addTrait(trait) {
+    this.traits.set(trait.name, trait);
+    this.states.set(trait.name, createInitialTraitState(trait));
+  }
+  /**
+   * Remove a trait from the manager.
+   */
+  removeTrait(traitName) {
+    this.traits.delete(traitName);
+    this.states.delete(traitName);
+  }
+  /**
+   * Get current state for a trait.
+   */
+  getState(traitName) {
+    return this.states.get(traitName);
+  }
+  /**
+   * Get all current states.
+   */
+  getAllStates() {
+    return new Map(this.states);
+  }
+  /**
+   * Check if a trait can handle an event from its current state.
+   */
+  canHandleEvent(traitName, eventKey) {
+    const trait = this.traits.get(traitName);
+    const state = this.states.get(traitName);
+    if (!trait || !state) return false;
+    return !!findTransition(trait, state.currentState, normalizeEventKey(eventKey));
+  }
+  /**
+   * Send an event to all traits.
+   *
+   * @returns Array of transition results (one per trait that had a matching transition)
+   */
+  sendEvent(eventKey, payload, entityData) {
+    const results = [];
+    for (const [traitName, trait] of this.traits) {
+      const traitState = this.states.get(traitName);
+      if (!traitState) continue;
+      const result = processEvent({
+        traitState,
+        trait,
+        eventKey,
+        payload,
+        entityData
+      });
+      if (result.executed) {
+        this.states.set(traitName, {
+          ...traitState,
+          currentState: result.newState,
+          previousState: result.previousState,
+          lastEvent: normalizeEventKey(eventKey),
+          context: { ...traitState.context, ...payload }
+        });
+        results.push({ traitName, result });
+      }
+    }
+    return results;
+  }
+  /**
+   * Reset a trait to its initial state.
+   */
+  resetTrait(traitName) {
+    const trait = this.traits.get(traitName);
+    if (trait) {
+      this.states.set(traitName, createInitialTraitState(trait));
+    }
+  }
+  /**
+   * Reset all traits to initial states.
+   */
+  resetAll() {
+    for (const [traitName, trait] of this.traits) {
+      this.states.set(traitName, createInitialTraitState(trait));
+    }
+  }
+};
+
+// src/EffectExecutor.ts
+function parseEffect(effect) {
+  if (!Array.isArray(effect) || effect.length === 0) {
+    return null;
+  }
+  const [operator, ...args] = effect;
+  if (typeof operator !== "string") {
+    return null;
+  }
+  return { operator, args };
+}
+function resolveArgs(args, bindings) {
+  const ctx = createContextFromBindings(bindings);
+  return args.map((arg) => interpolateValue(arg, ctx));
+}
+var EffectExecutor = class {
+  handlers;
+  bindings;
+  context;
+  debug;
+  constructor(options) {
+    this.handlers = options.handlers;
+    this.bindings = options.bindings;
+    this.context = options.context;
+    this.debug = options.debug ?? false;
+  }
+  /**
+   * Execute a single effect.
+   */
+  async execute(effect) {
+    const parsed = parseEffect(effect);
+    if (!parsed) {
+      if (this.debug) {
+        console.warn("[EffectExecutor] Invalid effect format:", effect);
+      }
+      return;
+    }
+    const { operator, args } = parsed;
+    const resolvedArgs = resolveArgs(args, this.bindings);
+    if (this.debug) {
+      console.log("[EffectExecutor] Executing:", operator, resolvedArgs);
+    }
+    try {
+      await this.dispatch(operator, resolvedArgs);
+    } catch (error) {
+      console.error("[EffectExecutor] Error executing effect:", operator, error);
+      throw error;
+    }
+  }
+  /**
+   * Execute multiple effects in sequence.
+   */
+  async executeAll(effects) {
+    for (const effect of effects) {
+      await this.execute(effect);
+    }
+  }
+  /**
+   * Execute multiple effects in parallel.
+   */
+  async executeParallel(effects) {
+    await Promise.all(effects.map((effect) => this.execute(effect)));
+  }
+  // ==========================================================================
+  // Effect Dispatch
+  // ==========================================================================
+  async dispatch(operator, args) {
+    switch (operator) {
+      // === Universal Effects ===
+      case "emit": {
+        const event = args[0];
+        const payload = args[1];
+        this.handlers.emit(event, payload);
+        break;
+      }
+      case "set": {
+        const [entityId, field, value] = args;
+        this.handlers.set(entityId, field, value);
+        break;
+      }
+      case "persist": {
+        const action = args[0];
+        const entityType = args[1];
+        const data = args[2];
+        await this.handlers.persist(action, entityType, data);
+        break;
+      }
+      case "call-service": {
+        const service = args[0];
+        const action = args[1];
+        const params = args[2];
+        await this.handlers.callService(service, action, params);
+        break;
+      }
+      case "fetch": {
+        if (this.handlers.fetch) {
+          const entityType = args[0];
+          const options = args[1];
+          await this.handlers.fetch(entityType, options);
+        } else {
+          this.logUnsupported("fetch");
+        }
+        break;
+      }
+      case "spawn": {
+        if (this.handlers.spawn) {
+          const entityType = args[0];
+          const props = args[1];
+          this.handlers.spawn(entityType, props);
+        } else {
+          this.logUnsupported("spawn");
+        }
+        break;
+      }
+      case "despawn": {
+        if (this.handlers.despawn) {
+          const entityId = args[0];
+          this.handlers.despawn(entityId);
+        } else {
+          this.logUnsupported("despawn");
+        }
+        break;
+      }
+      case "log": {
+        if (this.handlers.log) {
+          const message = args[0];
+          const level = args[1];
+          const data = args[2];
+          this.handlers.log(message, level, data);
+        } else {
+          console.log(args[0], args.slice(1));
+        }
+        break;
+      }
+      // === Client-Only Effects ===
+      case "render-ui":
+      case "render": {
+        if (this.handlers.renderUI) {
+          const slot = args[0];
+          const pattern = args[1];
+          const props = args[2];
+          const priority = args[3];
+          this.handlers.renderUI(slot, pattern, props, priority);
+        } else {
+          this.logUnsupported("render-ui");
+        }
+        break;
+      }
+      case "navigate": {
+        if (this.handlers.navigate) {
+          const path2 = args[0];
+          const params = args[1];
+          this.handlers.navigate(path2, params);
+        } else {
+          this.logUnsupported("navigate");
+        }
+        break;
+      }
+      case "notify": {
+        if (this.handlers.notify) {
+          const message = args[0];
+          const type = args[1] || "info";
+          this.handlers.notify(message, type);
+        } else {
+          console.log(`[Notify:${args[1] || "info"}] ${args[0]}`);
+        }
+        break;
+      }
+      // === Compound Effects ===
+      case "do": {
+        const nestedEffects = args;
+        for (const nested of nestedEffects) {
+          await this.execute(nested);
+        }
+        break;
+      }
+      case "when": {
+        const condition = args[0];
+        const thenEffect = args[1];
+        const elseEffect = args[2];
+        if (condition) {
+          await this.execute(thenEffect);
+        } else if (elseEffect) {
+          await this.execute(elseEffect);
+        }
+        break;
+      }
+      default: {
+        if (this.debug) {
+          console.warn("[EffectExecutor] Unknown operator:", operator);
+        }
+      }
+    }
+  }
+  logUnsupported(operator) {
+    if (this.debug) {
+      console.warn(
+        `[EffectExecutor] Effect "${operator}" not supported on this platform`
+      );
+    }
+  }
+};
+var MockPersistenceAdapter = class {
+  stores = /* @__PURE__ */ new Map();
+  schemas = /* @__PURE__ */ new Map();
+  idCounters = /* @__PURE__ */ new Map();
+  config;
+  constructor(config = {}) {
+    this.config = {
+      defaultSeedCount: 6,
+      debug: false,
+      ...config
+    };
+    if (config.seed !== void 0) {
+      faker.seed(config.seed);
+      if (this.config.debug) {
+        console.log(`[MockPersistence] Using seed: ${config.seed}`);
+      }
+    }
+  }
+  // ============================================================================
+  // Store Management
+  // ============================================================================
+  getStore(entityName) {
+    const normalized = entityName.toLowerCase();
+    if (!this.stores.has(normalized)) {
+      this.stores.set(normalized, /* @__PURE__ */ new Map());
+      this.idCounters.set(normalized, 0);
+    }
+    return this.stores.get(normalized);
+  }
+  nextId(entityName) {
+    const normalized = entityName.toLowerCase();
+    const counter = (this.idCounters.get(normalized) ?? 0) + 1;
+    this.idCounters.set(normalized, counter);
+    return `${this.capitalizeFirst(entityName)} Id ${counter}`;
+  }
+  // ============================================================================
+  // Schema & Seeding
+  // ============================================================================
+  /**
+   * Register an entity schema and seed mock data.
+   */
+  registerEntity(schema, seedCount) {
+    const normalized = schema.name.toLowerCase();
+    this.schemas.set(normalized, schema);
+    const count = seedCount ?? this.config.defaultSeedCount ?? 6;
+    this.seed(schema.name, schema.fields, count);
+  }
+  /**
+   * Seed an entity with mock data.
+   */
+  seed(entityName, fields, count) {
+    const store = this.getStore(entityName);
+    const normalized = entityName.toLowerCase();
+    if (this.config.debug) {
+      console.log(`[MockPersistence] Seeding ${count} ${entityName}...`);
+    }
+    for (let i = 0; i < count; i++) {
+      const item = this.generateMockItem(normalized, entityName, fields, i + 1);
+      store.set(item.id, item);
+    }
+  }
+  /**
+   * Generate a single mock item based on field schemas.
+   */
+  generateMockItem(normalizedName, entityName, fields, index) {
+    const id = this.nextId(entityName);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const item = {
+      id,
+      createdAt: faker.date.past({ years: 1 }).toISOString(),
+      updatedAt: now
+    };
+    for (const field of fields) {
+      if (field.name === "id" || field.name === "createdAt" || field.name === "updatedAt") {
+        continue;
+      }
+      item[field.name] = this.generateFieldValue(entityName, field, index);
+    }
+    return item;
+  }
+  /**
+   * Generate a mock value for a field based on its schema.
+   */
+  generateFieldValue(entityName, field, index) {
+    if (field.default !== void 0) {
+      if (field.default === "@now") {
+        return (/* @__PURE__ */ new Date()).toISOString();
+      }
+      return field.default;
+    }
+    if (!field.required && Math.random() > 0.8) {
+      return null;
+    }
+    const fieldType = field.type.toLowerCase();
+    switch (fieldType) {
+      case "string":
+        return this.generateStringValue(entityName, field, index);
+      case "number":
+        return faker.number.int({ min: 0, max: 100 });
+      case "boolean":
+        return faker.datatype.boolean();
+      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 null;
+      case "relation":
+        return null;
+      // Relations need special handling
+      case "array":
+      case "object":
+        return field.type === "array" ? [] : {};
+      default:
+        return this.generateStringValue(entityName, field, index);
+    }
+  }
+  /**
+   * Generate a string value based on field name heuristics.
+   */
+  generateStringValue(entityName, field, index) {
+    const name = field.name.toLowerCase();
+    if (field.values && field.values.length > 0) {
+      return faker.helpers.arrayElement(field.values);
+    }
+    if (name.includes("email")) return faker.internet.email();
+    if (name.includes("phone")) return faker.phone.number();
+    if (name.includes("address")) return faker.location.streetAddress();
+    if (name.includes("city")) return faker.location.city();
+    if (name.includes("country")) return faker.location.country();
+    if (name.includes("url") || name.includes("website")) return faker.internet.url();
+    if (name.includes("avatar") || name.includes("image")) return faker.image.avatar();
+    if (name.includes("color")) return faker.color.human();
+    if (name.includes("uuid")) return faker.string.uuid();
+    if (name.includes("description") || name.includes("bio")) return faker.lorem.paragraph();
+    const entityLabel = this.capitalizeFirst(entityName);
+    const fieldLabel = this.capitalizeFirst(field.name);
+    return `${entityLabel} ${fieldLabel} ${index}`;
+  }
+  /**
+   * Generate a date value based on field name heuristics.
+   */
+  generateDateValue(field) {
+    const name = field.name.toLowerCase();
+    let date;
+    if (name.includes("created") || name.includes("start") || name.includes("birth")) {
+      date = faker.date.past({ years: 2 });
+    } else if (name.includes("updated") || name.includes("modified")) {
+      date = faker.date.recent({ days: 30 });
+    } else if (name.includes("deadline") || name.includes("due") || name.includes("end") || name.includes("expires")) {
+      date = faker.date.future({ years: 1 });
+    } else {
+      date = faker.date.anytime();
+    }
+    return date.toISOString();
+  }
+  capitalizeFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+  // ============================================================================
+  // PersistenceAdapter Implementation
+  // ============================================================================
+  async create(entityType, data) {
+    const store = this.getStore(entityType);
+    const id = this.nextId(entityType);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const item = {
+      ...data,
+      id,
+      createdAt: now,
+      updatedAt: now
+    };
+    store.set(id, item);
+    return { id };
+  }
+  async update(entityType, id, data) {
+    const store = this.getStore(entityType);
+    const existing = store.get(id);
+    if (!existing) {
+      throw new Error(`Entity ${entityType} with id ${id} not found`);
+    }
+    const updated = {
+      ...existing,
+      ...data,
+      id,
+      // Preserve original ID
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    store.set(id, updated);
+  }
+  async delete(entityType, id) {
+    const store = this.getStore(entityType);
+    if (!store.has(id)) {
+      throw new Error(`Entity ${entityType} with id ${id} not found`);
+    }
+    store.delete(id);
+  }
+  async getById(entityType, id) {
+    const store = this.getStore(entityType);
+    return store.get(id) ?? null;
+  }
+  async list(entityType) {
+    const store = this.getStore(entityType);
+    return Array.from(store.values());
+  }
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+  /**
+   * Clear all data for an entity.
+   */
+  clear(entityName) {
+    const normalized = entityName.toLowerCase();
+    this.stores.delete(normalized);
+    this.idCounters.delete(normalized);
+  }
+  /**
+   * Clear all data.
+   */
+  clearAll() {
+    this.stores.clear();
+    this.idCounters.clear();
+  }
+  /**
+   * Get count of items for an entity.
+   */
+  count(entityName) {
+    const store = this.getStore(entityName);
+    return store.size;
+  }
+};
+
+// src/resolver/reference-resolver.ts
+init_external_loader();
+var ReferenceResolver = class {
+  loader;
+  options;
+  localTraits;
+  constructor(options) {
+    this.options = options;
+    this.loader = options.loader ?? new ExternalOrbitalLoader(options);
+    this.localTraits = options.localTraits ?? /* @__PURE__ */ new Map();
+  }
+  /**
+   * Resolve all references in an orbital.
+   */
+  async resolve(orbital, sourcePath, chain) {
+    const errors = [];
+    const warnings = [];
+    const importChain = chain ?? new ImportChain();
+    const importsResult = await this.resolveImports(
+      orbital.uses ?? [],
+      sourcePath,
+      importChain
+    );
+    if (!importsResult.success) {
+      return { success: false, errors: importsResult.errors };
+    }
+    const imports = importsResult.data;
+    const entityResult = this.resolveEntity(orbital.entity, imports);
+    if (!entityResult.success) {
+      errors.push(...entityResult.errors);
+    }
+    const traitsResult = this.resolveTraits(orbital.traits, imports);
+    if (!traitsResult.success) {
+      errors.push(...traitsResult.errors);
+    }
+    const pagesResult = this.resolvePages(orbital.pages, imports);
+    if (!pagesResult.success) {
+      errors.push(...pagesResult.errors);
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    if (!entityResult.success || !traitsResult.success || !pagesResult.success) {
+      return { success: false, errors: ["Internal error: unexpected failure state"] };
+    }
+    return {
+      success: true,
+      data: {
+        name: orbital.name,
+        entity: entityResult.data.entity,
+        entitySource: entityResult.data.source,
+        traits: traitsResult.data,
+        pages: pagesResult.data,
+        imports,
+        original: orbital
+      },
+      warnings
+    };
+  }
+  /**
+   * Resolve `uses` declarations to loaded orbitals.
+   */
+  async resolveImports(uses, sourcePath, chain) {
+    const errors = [];
+    const orbitals = /* @__PURE__ */ new Map();
+    if (this.options.skipExternalLoading) {
+      return {
+        success: true,
+        data: { orbitals },
+        warnings: ["External loading skipped"]
+      };
+    }
+    for (const use of uses) {
+      if (orbitals.has(use.as)) {
+        errors.push(`Duplicate import alias: ${use.as}`);
+        continue;
+      }
+      const loadResult = await this.loader.loadOrbital(
+        use.from,
+        void 0,
+        sourcePath,
+        chain
+      );
+      if (!loadResult.success) {
+        errors.push(`Failed to load "${use.from}" as "${use.as}": ${loadResult.error}`);
+        continue;
+      }
+      orbitals.set(use.as, {
+        alias: use.as,
+        from: use.from,
+        orbital: loadResult.data.orbital,
+        sourcePath: loadResult.data.sourcePath
+      });
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: { orbitals }, warnings: [] };
+  }
+  /**
+   * Resolve entity reference.
+   */
+  resolveEntity(entityRef, imports) {
+    if (!isEntityReference(entityRef)) {
+      return {
+        success: true,
+        data: { entity: entityRef },
+        warnings: []
+      };
+    }
+    const parsed = parseEntityRef(entityRef);
+    if (!parsed) {
+      return {
+        success: false,
+        errors: [`Invalid entity reference format: ${entityRef}. Expected "Alias.entity"`]
+      };
+    }
+    const imported = imports.orbitals.get(parsed.alias);
+    if (!imported) {
+      return {
+        success: false,
+        errors: [
+          `Unknown import alias in entity reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+        ]
+      };
+    }
+    const importedEntity = this.getEntityFromOrbital(imported.orbital);
+    if (!importedEntity) {
+      return {
+        success: false,
+        errors: [
+          `Imported orbital "${parsed.alias}" does not have an inline entity. Entity references cannot be chained.`
+        ]
+      };
+    }
+    const persistence = importedEntity.persistence ?? "persistent";
+    return {
+      success: true,
+      data: {
+        entity: importedEntity,
+        source: {
+          alias: parsed.alias,
+          persistence
+        }
+      },
+      warnings: []
+    };
+  }
+  /**
+   * Get the entity from an orbital (handling EntityRef).
+   */
+  getEntityFromOrbital(orbital) {
+    const entityRef = orbital.entity;
+    if (typeof entityRef === "string") {
+      return null;
+    }
+    return entityRef;
+  }
+  /**
+   * Resolve trait references.
+   */
+  resolveTraits(traitRefs, imports) {
+    const errors = [];
+    const resolved = [];
+    for (const traitRef of traitRefs) {
+      const result = this.resolveTraitRef(traitRef, imports);
+      if (!result.success) {
+        errors.push(...result.errors);
+      } else {
+        resolved.push(result.data);
+      }
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: resolved, warnings: [] };
+  }
+  /**
+   * Resolve a single trait reference.
+   */
+  resolveTraitRef(traitRef, imports) {
+    if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+      return {
+        success: true,
+        data: {
+          trait: traitRef,
+          source: { type: "inline" }
+        },
+        warnings: []
+      };
+    }
+    if (typeof traitRef !== "string" && "ref" in traitRef) {
+      const refObj = traitRef;
+      return this.resolveTraitRefString(refObj.ref, imports, refObj.config, refObj.linkedEntity);
+    }
+    if (typeof traitRef === "string") {
+      return this.resolveTraitRefString(traitRef, imports);
+    }
+    return {
+      success: false,
+      errors: [`Unknown trait reference format: ${JSON.stringify(traitRef)}`]
+    };
+  }
+  /**
+   * Resolve a trait reference string.
+   */
+  resolveTraitRefString(ref, imports, config, linkedEntity) {
+    const parsed = parseImportedTraitRef(ref);
+    if (parsed) {
+      const imported = imports.orbitals.get(parsed.alias);
+      if (!imported) {
+        return {
+          success: false,
+          errors: [
+            `Unknown import alias in trait reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+          ]
+        };
+      }
+      const trait = this.findTraitInOrbital(imported.orbital, parsed.traitName);
+      if (!trait) {
+        return {
+          success: false,
+          errors: [
+            `Trait "${parsed.traitName}" not found in imported orbital "${parsed.alias}". Available traits: ${this.listTraitsInOrbital(imported.orbital).join(", ") || "none"}`
+          ]
+        };
+      }
+      return {
+        success: true,
+        data: {
+          trait,
+          source: { type: "imported", alias: parsed.alias, traitName: parsed.traitName },
+          config,
+          linkedEntity
+        },
+        warnings: []
+      };
+    }
+    const localTrait = this.localTraits.get(ref);
+    if (localTrait) {
+      return {
+        success: true,
+        data: {
+          trait: localTrait,
+          source: { type: "local", name: ref },
+          config,
+          linkedEntity
+        },
+        warnings: []
+      };
+    }
+    return {
+      success: false,
+      errors: [
+        `Trait "${ref}" not found. For imported traits, use format "Alias.traits.TraitName". Local traits available: ${Array.from(this.localTraits.keys()).join(", ") || "none"}`
+      ]
+    };
+  }
+  /**
+   * Find a trait in an orbital by name.
+   */
+  findTraitInOrbital(orbital, traitName) {
+    for (const traitRef of orbital.traits) {
+      if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+        if (traitRef.name === traitName) {
+          return traitRef;
+        }
+      }
+      if (typeof traitRef !== "string" && "ref" in traitRef) {
+        const refObj = traitRef;
+        if (refObj.ref === traitName || refObj.name === traitName) ;
+      }
+    }
+    return null;
+  }
+  /**
+   * List trait names in an orbital.
+   */
+  listTraitsInOrbital(orbital) {
+    const names = [];
+    for (const traitRef of orbital.traits) {
+      if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
+        names.push(traitRef.name);
+      }
+    }
+    return names;
+  }
+  /**
+   * Resolve page references.
+   */
+  resolvePages(pageRefs, imports) {
+    const errors = [];
+    const resolved = [];
+    for (const pageRef of pageRefs) {
+      const result = this.resolvePageRef(pageRef, imports);
+      if (!result.success) {
+        errors.push(...result.errors);
+      } else {
+        resolved.push(result.data);
+      }
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: resolved, warnings: [] };
+  }
+  /**
+   * Resolve a single page reference.
+   */
+  resolvePageRef(pageRef, imports) {
+    if (!isPageReference(pageRef)) {
+      return {
+        success: true,
+        data: {
+          page: pageRef,
+          source: { type: "inline" },
+          pathOverridden: false
+        },
+        warnings: []
+      };
+    }
+    if (isPageReferenceString(pageRef)) {
+      return this.resolvePageRefString(pageRef, imports);
+    }
+    if (isPageReferenceObject(pageRef)) {
+      return this.resolvePageRefObject(pageRef, imports);
+    }
+    return {
+      success: false,
+      errors: [`Unknown page reference format: ${JSON.stringify(pageRef)}`]
+    };
+  }
+  /**
+   * Resolve a page reference string.
+   */
+  resolvePageRefString(ref, imports) {
+    const parsed = parsePageRef(ref);
+    if (!parsed) {
+      return {
+        success: false,
+        errors: [`Invalid page reference format: ${ref}. Expected "Alias.pages.PageName"`]
+      };
+    }
+    const imported = imports.orbitals.get(parsed.alias);
+    if (!imported) {
+      return {
+        success: false,
+        errors: [
+          `Unknown import alias in page reference: ${parsed.alias}. Available aliases: ${Array.from(imports.orbitals.keys()).join(", ") || "none"}`
+        ]
+      };
+    }
+    const page = this.findPageInOrbital(imported.orbital, parsed.pageName);
+    if (!page) {
+      return {
+        success: false,
+        errors: [
+          `Page "${parsed.pageName}" not found in imported orbital "${parsed.alias}". Available pages: ${this.listPagesInOrbital(imported.orbital).join(", ") || "none"}`
+        ]
+      };
+    }
+    return {
+      success: true,
+      data: {
+        page,
+        source: { type: "imported", alias: parsed.alias, pageName: parsed.pageName },
+        pathOverridden: false
+      },
+      warnings: []
+    };
+  }
+  /**
+   * Resolve a page reference object with optional path override.
+   */
+  resolvePageRefObject(refObj, imports) {
+    const baseResult = this.resolvePageRefString(refObj.ref, imports);
+    if (!baseResult.success) {
+      return baseResult;
+    }
+    const resolved = baseResult.data;
+    if (refObj.path) {
+      const originalPath = resolved.page.path;
+      resolved.page = {
+        ...resolved.page,
+        path: refObj.path
+      };
+      resolved.pathOverridden = true;
+      resolved.originalPath = originalPath;
+    }
+    return {
+      success: true,
+      data: resolved,
+      warnings: baseResult.warnings
+    };
+  }
+  /**
+   * Find a page in an orbital by name.
+   */
+  findPageInOrbital(orbital, pageName) {
+    const pages = orbital.pages;
+    if (!pages) return null;
+    for (const pageRef of pages) {
+      if (typeof pageRef !== "string" && !("ref" in pageRef)) {
+        const page = pageRef;
+        if (page.name === pageName) {
+          return { ...page };
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * List page names in an orbital.
+   */
+  listPagesInOrbital(orbital) {
+    const pages = orbital.pages;
+    if (!pages) return [];
+    const names = [];
+    for (const pageRef of pages) {
+      if (typeof pageRef !== "string" && !("ref" in pageRef)) {
+        names.push(pageRef.name);
+      }
+    }
+    return names;
+  }
+  /**
+   * Add local traits for resolution.
+   */
+  addLocalTraits(traits) {
+    for (const trait of traits) {
+      this.localTraits.set(trait.name, trait);
+    }
+  }
+  /**
+   * Clear loader cache.
+   */
+  clearCache() {
+    this.loader.clearCache();
+  }
+};
+async function resolveSchema(schema, options) {
+  const resolver = new ReferenceResolver(options);
+  const errors = [];
+  const warnings = [];
+  const resolved = [];
+  for (const orbital of schema.orbitals) {
+    const inlineTraits = orbital.traits.filter(
+      (t) => typeof t !== "string" && "stateMachine" in t
+    );
+    resolver.addLocalTraits(inlineTraits);
+  }
+  for (const orbital of schema.orbitals) {
+    const result = await resolver.resolve(orbital);
+    if (!result.success) {
+      errors.push(`Orbital "${orbital.name}": ${result.errors.join(", ")}`);
+    } else {
+      resolved.push(result.data);
+      warnings.push(...result.warnings.map((w) => `Orbital "${orbital.name}": ${w}`));
+    }
+  }
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+  return { success: true, data: resolved, warnings };
+}
+
+// src/loader/schema-loader.ts
+function isElectron() {
+  return typeof process !== "undefined" && !!process.versions?.electron;
+}
+function isBrowser() {
+  return typeof window !== "undefined" && !isElectron();
+}
+function isNode() {
+  return typeof process !== "undefined" && !isBrowser();
+}
+
+// src/loader/index.ts
+init_external_loader();
+var HttpImportChain = class _HttpImportChain {
+  chain = [];
+  /**
+   * Try to add a path to the chain.
+   * @returns Error message if circular, null if OK
+   */
+  push(absolutePath) {
+    if (this.chain.includes(absolutePath)) {
+      const cycle = [
+        ...this.chain.slice(this.chain.indexOf(absolutePath)),
+        absolutePath
+      ];
+      return `Circular import detected: ${cycle.join(" -> ")}`;
+    }
+    this.chain.push(absolutePath);
+    return null;
+  }
+  /**
+   * Remove the last path from the chain.
+   */
+  pop() {
+    this.chain.pop();
+  }
+  /**
+   * Clone the chain for nested loading.
+   */
+  clone() {
+    const newChain = new _HttpImportChain();
+    newChain.chain = [...this.chain];
+    return newChain;
+  }
+};
+var HttpLoaderCache = class {
+  cache = /* @__PURE__ */ new Map();
+  get(url) {
+    return this.cache.get(url);
+  }
+  set(url, schema) {
+    this.cache.set(url, schema);
+  }
+  has(url) {
+    return this.cache.has(url);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  get size() {
+    return this.cache.size;
+  }
+};
+var HttpLoader = class {
+  options;
+  cache;
+  constructor(options) {
+    this.options = {
+      basePath: options.basePath,
+      stdLibPath: options.stdLibPath ?? "",
+      scopedPaths: options.scopedPaths ?? {},
+      fetchOptions: options.fetchOptions,
+      timeout: options.timeout ?? 3e4,
+      credentials: options.credentials ?? "same-origin"
+    };
+    this.cache = new HttpLoaderCache();
+  }
+  /**
+   * Load a schema from an import path.
+   */
+  async load(importPath, fromPath, chain) {
+    const importChain = chain ?? new HttpImportChain();
+    const resolveResult = this.resolvePath(importPath, fromPath);
+    if (!resolveResult.success) {
+      return resolveResult;
+    }
+    const absoluteUrl = resolveResult.data;
+    const circularError = importChain.push(absoluteUrl);
+    if (circularError) {
+      return { success: false, error: circularError };
+    }
+    try {
+      const cached = this.cache.get(absoluteUrl);
+      if (cached) {
+        return { success: true, data: cached };
+      }
+      const loadResult = await this.fetchSchema(absoluteUrl);
+      if (!loadResult.success) {
+        return loadResult;
+      }
+      const loaded = {
+        schema: loadResult.data,
+        sourcePath: absoluteUrl,
+        importPath
+      };
+      this.cache.set(absoluteUrl, loaded);
+      return { success: true, data: loaded };
+    } finally {
+      importChain.pop();
+    }
+  }
+  /**
+   * Load a specific orbital from a schema by name.
+   */
+  async loadOrbital(importPath, orbitalName, fromPath, chain) {
+    const schemaResult = await this.load(importPath, fromPath, chain);
+    if (!schemaResult.success) {
+      return schemaResult;
+    }
+    const schema = schemaResult.data.schema;
+    let orbital;
+    if (orbitalName) {
+      const found = schema.orbitals.find(
+        (o) => o.name === orbitalName
+      );
+      if (!found) {
+        return {
+          success: false,
+          error: `Orbital "${orbitalName}" not found in ${importPath}. Available: ${schema.orbitals.map((o) => o.name).join(", ")}`
+        };
+      }
+      orbital = found;
+    } else {
+      if (schema.orbitals.length === 0) {
+        return {
+          success: false,
+          error: `No orbitals found in ${importPath}`
+        };
+      }
+      orbital = schema.orbitals[0];
+    }
+    return {
+      success: true,
+      data: {
+        orbital,
+        sourcePath: schemaResult.data.sourcePath,
+        importPath
+      }
+    };
+  }
+  /**
+   * Resolve an import path to an absolute URL.
+   */
+  resolvePath(importPath, fromPath) {
+    if (importPath.startsWith("http://") || importPath.startsWith("https://")) {
+      return { success: true, data: importPath };
+    }
+    if (importPath.startsWith("std/")) {
+      return this.resolveStdPath(importPath);
+    }
+    if (importPath.startsWith("@")) {
+      return this.resolveScopedPath(importPath);
+    }
+    if (importPath.startsWith("./") || importPath.startsWith("../")) {
+      return this.resolveRelativePath(importPath, fromPath);
+    }
+    return this.resolveRelativePath(`./${importPath}`, fromPath);
+  }
+  /**
+   * Resolve a standard library path.
+   */
+  resolveStdPath(importPath) {
+    if (!this.options.stdLibPath) {
+      return {
+        success: false,
+        error: `Standard library URL not configured. Cannot load: ${importPath}`
+      };
+    }
+    const relativePath = importPath.slice(4);
+    let absoluteUrl = this.joinUrl(this.options.stdLibPath, relativePath);
+    if (!absoluteUrl.endsWith(".orb")) {
+      absoluteUrl += ".orb";
+    }
+    return { success: true, data: absoluteUrl };
+  }
+  /**
+   * Resolve a scoped package path.
+   */
+  resolveScopedPath(importPath) {
+    const match = importPath.match(/^(@[^/]+)/);
+    if (!match) {
+      return {
+        success: false,
+        error: `Invalid scoped package path: ${importPath}`
+      };
+    }
+    const scope = match[1];
+    const scopeRoot = this.options.scopedPaths[scope];
+    if (!scopeRoot) {
+      return {
+        success: false,
+        error: `Scoped package "${scope}" not configured. Available: ${Object.keys(this.options.scopedPaths).join(", ") || "none"}`
+      };
+    }
+    const relativePath = importPath.slice(scope.length + 1);
+    let absoluteUrl = this.joinUrl(scopeRoot, relativePath);
+    if (!absoluteUrl.endsWith(".orb")) {
+      absoluteUrl += ".orb";
+    }
+    return { success: true, data: absoluteUrl };
+  }
+  /**
+   * Resolve a relative path.
+   */
+  resolveRelativePath(importPath, fromPath) {
+    const baseUrl = fromPath ? this.getParentUrl(fromPath) : this.options.basePath;
+    let absoluteUrl = this.joinUrl(baseUrl, importPath);
+    if (!absoluteUrl.endsWith(".orb")) {
+      absoluteUrl += ".orb";
+    }
+    return { success: true, data: absoluteUrl };
+  }
+  /**
+   * Fetch and parse an OrbitalSchema from a URL.
+   */
+  async fetchSchema(url) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(
+        () => controller.abort(),
+        this.options.timeout
+      );
+      try {
+        const response = await fetch(url, {
+          ...this.options.fetchOptions,
+          credentials: this.options.credentials,
+          signal: controller.signal,
+          headers: {
+            Accept: "application/json",
+            ...this.options.fetchOptions?.headers
+          }
+        });
+        if (!response.ok) {
+          return {
+            success: false,
+            error: `HTTP ${response.status}: ${response.statusText} for ${url}`
+          };
+        }
+        const text = await response.text();
+        let data;
+        try {
+          data = JSON.parse(text);
+        } catch (e) {
+          return {
+            success: false,
+            error: `Invalid JSON in ${url}: ${e instanceof Error ? e.message : String(e)}`
+          };
+        }
+        const parseResult = OrbitalSchemaSchema.safeParse(data);
+        if (!parseResult.success) {
+          const errors = parseResult.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+          return {
+            success: false,
+            error: `Invalid schema in ${url}:
+${errors}`
+          };
+        }
+        return { success: true, data: parseResult.data };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (e) {
+      if (e instanceof Error && e.name === "AbortError") {
+        return {
+          success: false,
+          error: `Request timeout for ${url} (${this.options.timeout}ms)`
+        };
+      }
+      return {
+        success: false,
+        error: `Failed to fetch ${url}: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+  }
+  /**
+   * Join URL parts, handling relative paths and trailing slashes.
+   */
+  joinUrl(base, path2) {
+    if (path2.startsWith("http://") || path2.startsWith("https://")) {
+      return path2;
+    }
+    if (typeof URL !== "undefined") {
+      try {
+        const baseUrl = base.endsWith("/") ? base : base + "/";
+        return new URL(path2, baseUrl).href;
+      } catch {
+      }
+    }
+    const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    const normalizedPath = path2.startsWith("/") ? path2 : "/" + path2;
+    if (normalizedPath.startsWith("/./")) {
+      return normalizedBase + normalizedPath.slice(2);
+    }
+    if (normalizedPath.startsWith("/../")) {
+      const baseParts = normalizedBase.split("/");
+      baseParts.pop();
+      return baseParts.join("/") + normalizedPath.slice(3);
+    }
+    return normalizedBase + normalizedPath;
+  }
+  /**
+   * Get parent URL (directory) from a URL.
+   */
+  getParentUrl(url) {
+    if (typeof URL !== "undefined") {
+      try {
+        const urlObj = new URL(url);
+        const pathParts = urlObj.pathname.split("/");
+        pathParts.pop();
+        urlObj.pathname = pathParts.join("/");
+        return urlObj.href;
+      } catch {
+      }
+    }
+    const lastSlash = url.lastIndexOf("/");
+    if (lastSlash !== -1) {
+      return url.slice(0, lastSlash);
+    }
+    return url;
+  }
+  /**
+   * Clear the cache.
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Get cache statistics.
+   */
+  getCacheStats() {
+    return { size: this.cache.size };
+  }
+};
+
+// src/loader/unified-loader.ts
+var externalLoaderModule = null;
+async function getExternalLoaderModule() {
+  if (externalLoaderModule) {
+    return externalLoaderModule;
+  }
+  if (isBrowser()) {
+    return null;
+  }
+  try {
+    externalLoaderModule = await Promise.resolve().then(() => (init_external_loader(), external_loader_exports));
+    return externalLoaderModule;
+  } catch {
+    return null;
+  }
+}
+var UnifiedImportChain = class _UnifiedImportChain {
+  chain = [];
+  push(path2) {
+    const normalized = this.normalizePath(path2);
+    if (this.chain.includes(normalized)) {
+      const cycle = [
+        ...this.chain.slice(this.chain.indexOf(normalized)),
+        normalized
+      ];
+      return `Circular import detected: ${cycle.join(" -> ")}`;
+    }
+    this.chain.push(normalized);
+    return null;
+  }
+  pop() {
+    this.chain.pop();
+  }
+  clone() {
+    const newChain = new _UnifiedImportChain();
+    newChain.chain = [...this.chain];
+    return newChain;
+  }
+  normalizePath(path2) {
+    if (path2.startsWith("http://") || path2.startsWith("https://")) {
+      return path2;
+    }
+    return path2.replace(/\\/g, "/");
+  }
+};
+var UnifiedLoader = class {
+  options;
+  httpLoader = null;
+  fsLoader = null;
+  fsLoaderInitialized = false;
+  cache = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = options;
+    this.httpLoader = new HttpLoader({
+      basePath: options.basePath,
+      stdLibPath: options.stdLibPath,
+      scopedPaths: options.scopedPaths,
+      ...options.http
+    });
+  }
+  /**
+   * Initialize the filesystem loader if available.
+   */
+  async initFsLoader() {
+    if (this.fsLoaderInitialized) {
+      return;
+    }
+    this.fsLoaderInitialized = true;
+    if (this.options.forceLoader === "http") {
+      return;
+    }
+    const module = await getExternalLoaderModule();
+    if (module) {
+      this.fsLoader = new module.ExternalOrbitalLoader({
+        basePath: this.options.basePath,
+        stdLibPath: this.options.stdLibPath,
+        scopedPaths: this.options.scopedPaths,
+        ...this.options.fileSystem
+      });
+    }
+  }
+  /**
+   * Determine which loader to use for an import path.
+   */
+  getLoaderForPath(importPath) {
+    if (this.options.forceLoader) {
+      return this.options.forceLoader;
+    }
+    if (importPath.startsWith("http://") || importPath.startsWith("https://")) {
+      return "http";
+    }
+    if (importPath.startsWith("std/") && this.options.stdLibPath) {
+      if (this.options.stdLibPath.startsWith("http://") || this.options.stdLibPath.startsWith("https://")) {
+        return "http";
+      }
+    }
+    if (importPath.startsWith("@") && this.options.scopedPaths) {
+      const match = importPath.match(/^(@[^/]+)/);
+      if (match) {
+        const scopePath = this.options.scopedPaths[match[1]];
+        if (scopePath && (scopePath.startsWith("http://") || scopePath.startsWith("https://"))) {
+          return "http";
+        }
+      }
+    }
+    if (isBrowser()) {
+      return "http";
+    }
+    return "filesystem";
+  }
+  /**
+   * Load a schema from an import path.
+   *
+   * Note: We delegate chain management to the inner loader (HttpLoader or FsLoader).
+   * The inner loader handles circular import detection, so we don't push/pop here.
+   * We only use the unified cache to avoid duplicate loads across loaders.
+   */
+  async load(importPath, fromPath, chain) {
+    await this.initFsLoader();
+    const importChain = chain ?? new UnifiedImportChain();
+    const loaderType = this.getLoaderForPath(importPath);
+    const resolveResult = this.resolvePath(importPath, fromPath);
+    if (!resolveResult.success) {
+      return resolveResult;
+    }
+    const absolutePath = resolveResult.data;
+    const cached = this.cache.get(absolutePath);
+    if (cached) {
+      return { success: true, data: cached };
+    }
+    let result;
+    if (loaderType === "http") {
+      if (!this.httpLoader) {
+        return {
+          success: false,
+          error: "HTTP loader not available"
+        };
+      }
+      result = await this.httpLoader.load(importPath, fromPath, importChain);
+    } else {
+      if (!this.fsLoader) {
+        if (this.httpLoader) {
+          result = await this.httpLoader.load(
+            importPath,
+            fromPath,
+            importChain
+          );
+        } else {
+          return {
+            success: false,
+            error: `Filesystem loader not available and import "${importPath}" cannot be loaded via HTTP. This typically happens when loading local files in a browser environment.`
+          };
+        }
+      } else {
+        result = await this.fsLoader.load(importPath, fromPath, importChain);
+      }
+    }
+    if (result.success) {
+      this.cache.set(absolutePath, result.data);
+    }
+    return result;
+  }
+  /**
+   * Load a specific orbital from a schema by name.
+   */
+  async loadOrbital(importPath, orbitalName, fromPath, chain) {
+    const schemaResult = await this.load(importPath, fromPath, chain);
+    if (!schemaResult.success) {
+      return schemaResult;
+    }
+    const schema = schemaResult.data.schema;
+    if (orbitalName) {
+      const found = schema.orbitals.find((o) => o.name === orbitalName);
+      if (!found) {
+        return {
+          success: false,
+          error: `Orbital "${orbitalName}" not found in ${importPath}. Available: ${schema.orbitals.map((o) => o.name).join(", ")}`
+        };
+      }
+      return {
+        success: true,
+        data: {
+          orbital: found,
+          sourcePath: schemaResult.data.sourcePath,
+          importPath
+        }
+      };
+    }
+    if (schema.orbitals.length === 0) {
+      return {
+        success: false,
+        error: `No orbitals found in ${importPath}`
+      };
+    }
+    return {
+      success: true,
+      data: {
+        orbital: schema.orbitals[0],
+        sourcePath: schemaResult.data.sourcePath,
+        importPath
+      }
+    };
+  }
+  /**
+   * Resolve an import path to an absolute path/URL.
+   */
+  resolvePath(importPath, fromPath) {
+    const loaderType = this.getLoaderForPath(importPath);
+    if (loaderType === "http" && this.httpLoader) {
+      return this.httpLoader.resolvePath(importPath, fromPath);
+    }
+    if (this.fsLoader) {
+      return this.fsLoader.resolvePath(importPath, fromPath);
+    }
+    if (this.httpLoader) {
+      return this.httpLoader.resolvePath(importPath, fromPath);
+    }
+    return {
+      success: false,
+      error: "No loader available for path resolution"
+    };
+  }
+  /**
+   * Clear all caches.
+   */
+  clearCache() {
+    this.cache.clear();
+    this.httpLoader?.clearCache();
+    this.fsLoader?.clearCache();
+  }
+  /**
+   * Get combined cache statistics.
+   */
+  getCacheStats() {
+    let size = this.cache.size;
+    if (this.httpLoader) {
+      size += this.httpLoader.getCacheStats().size;
+    }
+    if (this.fsLoader) {
+      size += this.fsLoader.getCacheStats().size;
+    }
+    return { size };
+  }
+  /**
+   * Check if filesystem loading is available.
+   */
+  async hasFilesystemAccess() {
+    await this.initFsLoader();
+    return this.fsLoader !== null;
+  }
+  /**
+   * Get current environment info.
+   */
+  getEnvironmentInfo() {
+    return {
+      isElectron: isElectron(),
+      isBrowser: isBrowser(),
+      isNode: isNode(),
+      hasFilesystem: this.fsLoader !== null
+    };
+  }
+};
+function createUnifiedLoader(options) {
+  return new UnifiedLoader(options);
+}
+
+// src/UsesIntegration.ts
+async function preprocessSchema(schema, options) {
+  const namespaceEvents = options.namespaceEvents ?? true;
+  const resolveResult = await resolveSchema(schema, options);
+  if (!resolveResult.success) {
+    return { success: false, errors: resolveResult.errors };
+  }
+  const resolved = resolveResult.data;
+  const warnings = resolveResult.warnings;
+  const preprocessedOrbitals = [];
+  const entitySharing = {};
+  const eventNamespaces = {};
+  for (const resolvedOrbital of resolved) {
+    const orbitalName = resolvedOrbital.name;
+    const persistence = resolvedOrbital.entitySource?.persistence ?? resolvedOrbital.entity.persistence ?? "persistent";
+    entitySharing[orbitalName] = {
+      entityName: resolvedOrbital.entity.name,
+      persistence,
+      isShared: persistence !== "runtime",
+      sourceAlias: resolvedOrbital.entitySource?.alias,
+      collectionName: resolvedOrbital.entity.collection
+    };
+    eventNamespaces[orbitalName] = {};
+    for (const resolvedTrait of resolvedOrbital.traits) {
+      const traitName = resolvedTrait.trait.name;
+      const namespace = {
+        emits: {},
+        listens: {}
+      };
+      if (namespaceEvents && resolvedTrait.source.type === "imported") {
+        const emits = resolvedTrait.trait.emits ?? [];
+        for (const emit of emits) {
+          const eventName = typeof emit === "string" ? emit : emit.event;
+          namespace.emits[eventName] = `${orbitalName}.${traitName}.${eventName}`;
+        }
+        const listens = resolvedTrait.trait.listens ?? [];
+        for (const listen of listens) {
+          namespace.listens[listen.event] = listen.event;
+        }
+      }
+      eventNamespaces[orbitalName][traitName] = namespace;
+    }
+    const preprocessedOrbital = {
+      name: orbitalName,
+      description: resolvedOrbital.original.description,
+      visual_prompt: resolvedOrbital.original.visual_prompt,
+      // Resolved entity (always inline now)
+      entity: resolvedOrbital.entity,
+      // Resolved traits (inline definitions)
+      traits: resolvedOrbital.traits.map((rt) => {
+        if (rt.config || rt.linkedEntity) {
+          return {
+            ref: rt.trait.name,
+            config: rt.config,
+            linkedEntity: rt.linkedEntity,
+            // Include the resolved trait definition for runtime
+            _resolved: rt.trait
+          };
+        }
+        return rt.trait;
+      }),
+      // Resolved pages (inline definitions with path overrides applied)
+      pages: resolvedOrbital.pages.map((rp) => rp.page),
+      // Preserve other fields
+      exposes: resolvedOrbital.original.exposes,
+      domainContext: resolvedOrbital.original.domainContext,
+      design: resolvedOrbital.original.design
+    };
+    preprocessedOrbitals.push(preprocessedOrbital);
+  }
+  const preprocessedSchema = {
+    ...schema,
+    orbitals: preprocessedOrbitals
+  };
+  return {
+    success: true,
+    data: {
+      schema: preprocessedSchema,
+      entitySharing,
+      eventNamespaces,
+      warnings
+    }
+  };
+}
+
+// src/OrbitalServerRuntime.ts
+var InMemoryPersistence = class {
+  data = /* @__PURE__ */ new Map();
+  idCounter = 0;
+  async create(entityType, data) {
+    const id = `${entityType}-${++this.idCounter}`;
+    if (!this.data.has(entityType)) {
+      this.data.set(entityType, /* @__PURE__ */ new Map());
+    }
+    this.data.get(entityType).set(id, { ...data, id });
+    return { id };
+  }
+  async update(entityType, id, data) {
+    const collection = this.data.get(entityType);
+    if (collection?.has(id)) {
+      const existing = collection.get(id);
+      collection.set(id, { ...existing, ...data });
+    }
+  }
+  async delete(entityType, id) {
+    this.data.get(entityType)?.delete(id);
+  }
+  async getById(entityType, id) {
+    return this.data.get(entityType)?.get(id) || null;
+  }
+  async list(entityType) {
+    const collection = this.data.get(entityType);
+    return collection ? Array.from(collection.values()) : [];
+  }
+};
+var OrbitalServerRuntime = class {
+  orbitals = /* @__PURE__ */ new Map();
+  eventBus;
+  config;
+  persistence;
+  listenerCleanups = [];
+  tickBindings = [];
+  loader = null;
+  preprocessedCache = /* @__PURE__ */ new Map();
+  entitySharingMap = {};
+  eventNamespaceMap = {};
+  constructor(config = {}) {
+    this.config = {
+      mode: "mock",
+      // Default to mock mode for preview
+      autoPreprocess: false,
+      namespaceEvents: true,
+      ...config
+    };
+    this.eventBus = new EventBus();
+    if (config.loaderConfig) {
+      this.loader = config.loaderConfig.loader ?? createUnifiedLoader({
+        basePath: config.loaderConfig.basePath,
+        stdLibPath: config.loaderConfig.stdLibPath,
+        scopedPaths: config.loaderConfig.scopedPaths
+      });
+    }
+    if (this.config.mode === "mock" && !config.persistence) {
+      this.persistence = new MockPersistenceAdapter({
+        seed: config.mockSeed,
+        defaultSeedCount: config.mockSeedCount ?? 6,
+        debug: config.debug
+      });
+      if (config.debug) {
+        console.log("[OrbitalRuntime] Using mock persistence with faker data");
+      }
+    } else {
+      this.persistence = config.persistence || new InMemoryPersistence();
+    }
+  }
+  // ==========================================================================
+  // Schema Registration
+  // ==========================================================================
+  /**
+   * Register an OrbitalSchema for execution.
+   *
+   * If `autoPreprocess` is enabled in config and schema has `uses` declarations,
+   * it will be preprocessed first to resolve imports.
+   *
+   * For explicit preprocessing control, use `registerWithPreprocess()`.
+   */
+  register(schema) {
+    if (this.config.debug) {
+      console.log(`[OrbitalRuntime] Registering schema: ${schema.name}`);
+    }
+    for (const orbital of schema.orbitals) {
+      this.registerOrbital(orbital);
+    }
+    this.setupEventListeners();
+    this.setupTicks();
+  }
+  /**
+   * Register an OrbitalSchema with preprocessing to resolve `uses` imports.
+   *
+   * This method:
+   * 1. Loads all external orbitals referenced in `uses` declarations
+   * 2. Expands entity/trait/page references to inline definitions
+   * 3. Builds entity sharing and event namespace maps
+   * 4. Caches the preprocessed result
+   * 5. Registers the resolved schema
+   *
+   * @param schema - Schema with potential `uses` declarations
+   * @param options - Optional preprocessing options
+   * @returns Preprocessing result with entity sharing info
+   *
+   * @example
+   * ```typescript
+   * const runtime = new OrbitalServerRuntime({
+   *   loaderConfig: {
+   *     basePath: '/schemas',
+   *     stdLibPath: '/std',
+   *   },
+   * });
+   *
+   * const result = await runtime.registerWithPreprocess(schema);
+   * if (result.success) {
+   *   console.log('Registered with', Object.keys(result.entitySharing).length, 'orbitals');
+   * }
+   * ```
+   */
+  async registerWithPreprocess(schema, options) {
+    if (!this.loader && !this.config.loaderConfig) {
+      return {
+        success: false,
+        errors: ["Loader not configured. Set loaderConfig in OrbitalServerRuntimeConfig."]
+      };
+    }
+    if (!this.loader && this.config.loaderConfig) {
+      this.loader = this.config.loaderConfig.loader ?? createUnifiedLoader({
+        basePath: this.config.loaderConfig.basePath,
+        stdLibPath: this.config.loaderConfig.stdLibPath,
+        scopedPaths: this.config.loaderConfig.scopedPaths
+      });
+    }
+    const cacheKey = `${schema.name}:${schema.version || "1.0.0"}`;
+    const cached = this.preprocessedCache.get(cacheKey);
+    if (cached) {
+      if (this.config.debug) {
+        console.log(`[OrbitalRuntime] Using cached preprocessed schema: ${schema.name}`);
+      }
+      this.register(cached.schema);
+      this.entitySharingMap = { ...this.entitySharingMap, ...cached.entitySharing };
+      this.eventNamespaceMap = { ...this.eventNamespaceMap, ...cached.eventNamespaces };
+      return {
+        success: true,
+        entitySharing: cached.entitySharing,
+        eventNamespaces: cached.eventNamespaces,
+        warnings: cached.warnings
+      };
+    }
+    if (this.config.debug) {
+      console.log(`[OrbitalRuntime] Preprocessing schema: ${schema.name}`);
+    }
+    const result = await preprocessSchema(schema, {
+      basePath: this.config.loaderConfig?.basePath || ".",
+      stdLibPath: this.config.loaderConfig?.stdLibPath,
+      scopedPaths: this.config.loaderConfig?.scopedPaths,
+      loader: this.loader,
+      namespaceEvents: this.config.namespaceEvents
+    });
+    if (!result.success) {
+      return {
+        success: false,
+        errors: result.errors
+      };
+    }
+    this.preprocessedCache.set(cacheKey, result.data);
+    this.entitySharingMap = { ...this.entitySharingMap, ...result.data.entitySharing };
+    this.eventNamespaceMap = { ...this.eventNamespaceMap, ...result.data.eventNamespaces };
+    this.register(result.data.schema);
+    return {
+      success: true,
+      entitySharing: result.data.entitySharing,
+      eventNamespaces: result.data.eventNamespaces,
+      warnings: result.data.warnings
+    };
+  }
+  /**
+   * Get entity sharing information for registered orbitals.
+   * Useful for determining entity isolation and collection names.
+   */
+  getEntitySharing() {
+    return { ...this.entitySharingMap };
+  }
+  /**
+   * Get event namespace mapping for registered orbitals.
+   * Useful for debugging cross-orbital event routing.
+   */
+  getEventNamespaces() {
+    return { ...this.eventNamespaceMap };
+  }
+  /**
+   * Clear the preprocessing cache.
+   */
+  clearPreprocessCache() {
+    this.preprocessedCache.clear();
+  }
+  /**
+   * Register a single orbital
+   */
+  registerOrbital(orbital) {
+    const traitDefs = orbital.traits.map((t) => {
+      const stateMachine = t.stateMachine;
+      const states = t.states || stateMachine?.states || [];
+      const transitions = t.transitions || stateMachine?.transitions || [];
+      return {
+        name: t.name,
+        states,
+        transitions,
+        listens: t.listens
+      };
+    });
+    const manager = new StateMachineManager(traitDefs);
+    this.orbitals.set(orbital.name, {
+      schema: orbital,
+      manager,
+      entityData: /* @__PURE__ */ new Map()
+    });
+    console.log(`[OrbitalRuntime] Checking mock seed: mode=${this.config.mode}, isMockAdapter=${this.persistence instanceof MockPersistenceAdapter}`);
+    if (this.config.mode === "mock" && this.persistence instanceof MockPersistenceAdapter) {
+      const entity = orbital.entity;
+      console.log(`[OrbitalRuntime] Entity:`, entity?.name, "fields:", entity?.fields?.length);
+      if (entity?.name && entity.fields) {
+        const fields = entity.fields.map((f) => ({
+          name: f.name,
+          type: f.type,
+          required: f.required,
+          values: f.values,
+          default: f.default
+        }));
+        this.persistence.registerEntity({ name: entity.name, fields });
+        console.log(`[OrbitalRuntime] Seeded mock data for entity: ${entity.name}, count: ${this.persistence.count(entity.name)}`);
+      }
+    } else {
+      console.log(`[OrbitalRuntime] Mock seeding SKIPPED`);
+    }
+    if (this.config.debug) {
+      console.log(
+        `[OrbitalRuntime] Registered orbital: ${orbital.name} with ${orbital.traits.length} trait(s)`
+      );
+    }
+  }
+  /**
+   * Set up event listeners for cross-orbital communication
+   */
+  setupEventListeners() {
+    for (const cleanup of this.listenerCleanups) {
+      cleanup();
+    }
+    this.listenerCleanups = [];
+    for (const [orbitalName, registered] of this.orbitals) {
+      for (const trait of registered.schema.traits) {
+        if (!trait.listens) continue;
+        for (const listener of trait.listens) {
+          const cleanup = this.eventBus.on(listener.event, async (event) => {
+            if (this.config.debug) {
+              console.log(
+                `[OrbitalRuntime] ${orbitalName}.${trait.name} received: ${listener.event}`
+              );
+            }
+            let mappedPayload = event.payload;
+            if (listener.payloadMapping && event.payload) {
+              mappedPayload = {};
+              for (const [key, expr] of Object.entries(
+                listener.payloadMapping
+              )) {
+                if (typeof expr === "string" && expr.startsWith("@payload.")) {
+                  const field = expr.slice("@payload.".length);
+                  mappedPayload[key] = event.payload[field];
+                } else {
+                  mappedPayload[key] = expr;
+                }
+              }
+            }
+            await this.processOrbitalEvent(orbitalName, {
+              event: listener.triggers,
+              payload: mappedPayload
+            });
+          });
+          this.listenerCleanups.push(cleanup);
+        }
+      }
+    }
+  }
+  /**
+   * Set up scheduled ticks for all traits
+   */
+  setupTicks() {
+    this.cleanupTicks();
+    for (const [orbitalName, registered] of this.orbitals) {
+      for (const trait of registered.schema.traits) {
+        if (!trait.ticks || trait.ticks.length === 0) continue;
+        for (const tick of trait.ticks) {
+          this.registerTick(orbitalName, trait.name, tick, registered);
+        }
+      }
+    }
+    if (this.config.debug && this.tickBindings.length > 0) {
+      console.log(
+        `[OrbitalRuntime] Registered ${this.tickBindings.length} tick(s)`
+      );
+    }
+  }
+  /**
+   * Register a single tick
+   */
+  registerTick(orbitalName, traitName, tick, registered) {
+    let intervalMs;
+    if (typeof tick.interval === "number") {
+      intervalMs = tick.interval;
+    } else if (typeof tick.interval === "string") {
+      intervalMs = this.parseIntervalString(tick.interval);
+    } else {
+      intervalMs = 1e3;
+    }
+    if (this.config.debug) {
+      console.log(
+        `[OrbitalRuntime] Registering tick: ${orbitalName}.${traitName}.${tick.name} (${intervalMs}ms)`
+      );
+    }
+    const timerId = setInterval(async () => {
+      await this.executeTick(orbitalName, traitName, tick, registered);
+    }, intervalMs);
+    this.tickBindings.push({
+      orbitalName,
+      traitName,
+      tick,
+      timerId
+    });
+  }
+  /**
+   * Parse interval string to milliseconds
+   * Supports: '5s', '1m', '1h', '30000' (ms)
+   */
+  parseIntervalString(interval) {
+    const match = interval.match(/^(\d+)(ms|s|m|h)?$/);
+    if (!match) {
+      console.warn(
+        `[OrbitalRuntime] Invalid interval format: ${interval}, defaulting to 1000ms`
+      );
+      return 1e3;
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2] || "ms";
+    switch (unit) {
+      case "ms":
+        return value;
+      case "s":
+        return value * 1e3;
+      case "m":
+        return value * 60 * 1e3;
+      case "h":
+        return value * 60 * 60 * 1e3;
+      default:
+        return value;
+    }
+  }
+  /**
+   * Execute a tick for all applicable entities
+   */
+  async executeTick(orbitalName, traitName, tick, registered) {
+    const entityType = registered.schema.entity.name;
+    const emittedEvents = [];
+    try {
+      let entities = await this.persistence.list(entityType);
+      if (tick.appliesTo && tick.appliesTo.length > 0) {
+        const appliesToSet = new Set(tick.appliesTo);
+        entities = entities.filter((e) => appliesToSet.has(e.id));
+      }
+      if (this.config.debug && entities.length > 0) {
+        console.log(
+          `[OrbitalRuntime] Tick ${orbitalName}.${traitName}.${tick.name}: processing ${entities.length} entities`
+        );
+      }
+      for (const entity of entities) {
+        if (tick.guard) {
+          try {
+            const ctx = createContextFromBindings({
+              entity,
+              payload: {},
+              state: registered.manager.getState(traitName)?.currentState || "unknown"
+            });
+            const guardPasses = evaluateGuard(
+              tick.guard,
+              ctx
+            );
+            if (!guardPasses) {
+              if (this.config.debug) {
+                console.log(
+                  `[OrbitalRuntime] Tick ${tick.name}: guard failed for entity ${entity.id}`
+                );
+              }
+              continue;
+            }
+          } catch (error) {
+            console.error(
+              `[OrbitalRuntime] Tick ${tick.name}: guard evaluation error for entity ${entity.id}:`,
+              error
+            );
+            continue;
+          }
+        }
+        if (tick.effects && tick.effects.length > 0) {
+          const fetchedData = {};
+          const clientEffects = [];
+          const tickEffectResults = [];
+          await this.executeEffects(
+            registered,
+            traitName,
+            tick.effects,
+            {},
+            // No payload for ticks
+            entity,
+            entity.id,
+            emittedEvents,
+            fetchedData,
+            clientEffects,
+            tickEffectResults
+          );
+          if (this.config.debug) {
+            console.log(
+              `[OrbitalRuntime] Tick ${tick.name}: executed effects for entity ${entity.id}`
+            );
+          }
+        }
+      }
+    } catch (error) {
+      console.error(
+        `[OrbitalRuntime] Tick ${tick.name} execution error:`,
+        error
+      );
+    }
+  }
+  /**
+   * Clean up all active ticks
+   */
+  cleanupTicks() {
+    for (const binding of this.tickBindings) {
+      clearInterval(binding.timerId);
+    }
+    this.tickBindings = [];
+  }
+  /**
+   * Unregister all orbitals and clean up
+   */
+  unregisterAll() {
+    this.cleanupTicks();
+    for (const cleanup of this.listenerCleanups) {
+      cleanup();
+    }
+    this.listenerCleanups = [];
+    this.orbitals.clear();
+    this.eventBus.clear();
+  }
+  // ==========================================================================
+  // Event Processing
+  // ==========================================================================
+  /**
+   * Process an event for an orbital
+   */
+  async processOrbitalEvent(orbitalName, request) {
+    const registered = this.orbitals.get(orbitalName);
+    if (!registered) {
+      return {
+        success: false,
+        transitioned: false,
+        states: {},
+        emittedEvents: [],
+        error: `Orbital not found: ${orbitalName}`
+      };
+    }
+    const { event, payload, entityId, user } = request;
+    const emittedEvents = [];
+    const fetchedData = {};
+    const clientEffects = [];
+    const effectResults = [];
+    const activeTraits = payload?._activeTraits;
+    const cleanPayload = payload ? { ...payload } : void 0;
+    if (cleanPayload) {
+      delete cleanPayload._activeTraits;
+    }
+    let entityData = {};
+    if (entityId) {
+      const stored = await this.persistence.getById(
+        registered.schema.entity.name,
+        entityId
+      );
+      if (stored) {
+        entityData = stored;
+      }
+    }
+    const results = registered.manager.sendEvent(event, cleanPayload, entityData);
+    const filteredResults = activeTraits && activeTraits.length > 0 ? results.filter(({ traitName }) => activeTraits.includes(traitName)) : results;
+    if (this.config.debug && activeTraits) {
+      console.log(`[OrbitalRuntime] Filtering traits: ${results.length} total, ${filteredResults.length} active (${activeTraits.join(", ")})`);
+    }
+    for (const { traitName, result } of filteredResults) {
+      if (result.effects.length > 0) {
+        await this.executeEffects(
+          registered,
+          traitName,
+          result.effects,
+          cleanPayload,
+          entityData,
+          entityId,
+          emittedEvents,
+          fetchedData,
+          clientEffects,
+          effectResults,
+          user
+        );
+      }
+    }
+    const states = {};
+    for (const [name, state] of registered.manager.getAllStates()) {
+      states[name] = state.currentState;
+    }
+    const response = {
+      success: true,
+      transitioned: results.length > 0,
+      states,
+      emittedEvents
+    };
+    if (Object.keys(fetchedData).length > 0) {
+      response.data = fetchedData;
+    }
+    if (clientEffects.length > 0) {
+      response.clientEffects = clientEffects;
+    }
+    if (effectResults.length > 0) {
+      response.effectResults = effectResults;
+    }
+    return response;
+  }
+  /**
+   * Execute effects from a transition
+   */
+  async executeEffects(registered, traitName, effects, payload, entityData, entityId, emittedEvents, fetchedData, clientEffects, effectResults, user) {
+    const entityType = registered.schema.entity.name;
+    const handlers = {
+      emit: (event, eventPayload) => {
+        if (this.config.debug) {
+          console.log(`[OrbitalRuntime] Emitting: ${event}`, eventPayload);
+        }
+        this.eventBus.emit(event, eventPayload);
+        emittedEvents.push({ event, payload: eventPayload });
+      },
+      set: async (targetId, field, value) => {
+        const id = targetId || entityId;
+        if (id) {
+          try {
+            await this.persistence.update(entityType, id, { [field]: value });
+            effectResults.push({
+              effect: "set",
+              entityType,
+              data: { id, field, value },
+              success: true
+            });
+          } catch (err) {
+            effectResults.push({
+              effect: "set",
+              entityType,
+              data: { id, field, value },
+              success: false,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+      },
+      persist: async (action, targetEntityType, data) => {
+        const type = targetEntityType || entityType;
+        let resultData;
+        try {
+          switch (action) {
+            case "create": {
+              const { id } = await this.persistence.create(type, data || {});
+              resultData = { id, ...data || {} };
+              break;
+            }
+            case "update":
+              if (data?.id || entityId) {
+                const updateId = data?.id || entityId;
+                await this.persistence.update(type, updateId, data || {});
+                const updated = await this.persistence.getById(type, updateId);
+                resultData = updated || { id: updateId, ...data || {} };
+              }
+              break;
+            case "delete":
+              if (data?.id || entityId) {
+                const deleteId = data?.id || entityId;
+                await this.persistence.delete(type, deleteId);
+                resultData = { id: deleteId, deleted: true };
+              }
+              break;
+          }
+          effectResults.push({
+            effect: "persist",
+            action,
+            entityType: type,
+            data: resultData,
+            success: true
+          });
+        } catch (err) {
+          effectResults.push({
+            effect: "persist",
+            action,
+            entityType: type,
+            success: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      },
+      callService: async (service, action, params) => {
+        try {
+          let result = null;
+          if (this.config.effectHandlers?.callService) {
+            result = await this.config.effectHandlers.callService(
+              service,
+              action,
+              params
+            );
+          } else {
+            console.warn(
+              `[OrbitalRuntime] call-service not configured: ${service}.${action}`
+            );
+          }
+          effectResults.push({
+            effect: "call-service",
+            action: `${service}.${action}`,
+            data: result,
+            success: true
+          });
+          return result;
+        } catch (err) {
+          effectResults.push({
+            effect: "call-service",
+            action: `${service}.${action}`,
+            success: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+          return null;
+        }
+      },
+      fetch: async (fetchEntityType, options) => {
+        try {
+          if (options?.id) {
+            const entity = await this.persistence.getById(fetchEntityType, options.id);
+            if (entity) {
+              fetchedData[fetchEntityType] = [entity];
+            }
+            return entity;
+          } else {
+            let entities = await this.persistence.list(fetchEntityType);
+            if (options?.offset && options.offset > 0) {
+              entities = entities.slice(options.offset);
+            }
+            if (options?.limit && options.limit > 0) {
+              entities = entities.slice(0, options.limit);
+            }
+            fetchedData[fetchEntityType] = entities;
+            return entities;
+          }
+        } catch (error) {
+          console.error(`[OrbitalRuntime] Fetch error for ${fetchEntityType}:`, error);
+          return null;
+        }
+      },
+      // Client-side effects - collect for forwarding to client
+      renderUI: (slot, pattern, props, priority) => {
+        clientEffects.push(["render-ui", slot, pattern, props, priority]);
+      },
+      navigate: (path2, params) => {
+        clientEffects.push(["navigate", path2, params]);
+      },
+      notify: (message, type) => {
+        if (this.config.debug) {
+          console.log(`[OrbitalRuntime] Notification (${type}): ${message}`);
+        }
+        clientEffects.push(["notify", message, { type }]);
+      },
+      log: (message, level) => {
+        const logFn = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+        logFn(`[OrbitalRuntime] ${message}`);
+      },
+      // Allow custom handlers to override
+      ...this.config.effectHandlers
+    };
+    const state = registered.manager.getState(traitName);
+    const bindings = {
+      entity: entityData,
+      payload,
+      state: state?.currentState || "unknown",
+      user
+      // @user bindings from Firebase auth
+    };
+    const context = {
+      traitName,
+      state: state?.currentState || "unknown",
+      transition: "unknown",
+      entityId
+    };
+    const executor = new EffectExecutor({
+      handlers,
+      bindings,
+      context,
+      debug: this.config.debug
+    });
+    await executor.executeAll(effects);
+  }
+  // ==========================================================================
+  // Express Router
+  // ==========================================================================
+  /**
+   * Create Express router for orbital API endpoints
+   *
+   * All data access goes through trait events with guards.
+   * No direct CRUD routes - use events with `fetch` effects.
+   *
+   * Routes:
+   * - GET  /              - List registered orbitals
+   * - GET  /:orbital      - Get orbital info and current states
+   * - POST /:orbital/events - Send event to orbital (includes data from `fetch` effects)
+   */
+  router() {
+    const router = Router();
+    router.get("/", (_req, res) => {
+      const orbitals = Array.from(this.orbitals.entries()).map(
+        ([name, reg]) => ({
+          name,
+          entity: reg.schema.entity.name,
+          traits: reg.schema.traits.map((t) => t.name)
+        })
+      );
+      res.json({ success: true, orbitals });
+    });
+    router.get("/:orbital", (req, res) => {
+      const orbitalName = req.params.orbital;
+      const registered = this.orbitals.get(orbitalName);
+      if (!registered) {
+        res.status(404).json({ success: false, error: "Orbital not found" });
+        return;
+      }
+      const states = {};
+      for (const [name, state] of registered.manager.getAllStates()) {
+        states[name] = state.currentState;
+      }
+      res.json({
+        success: true,
+        orbital: {
+          name: orbitalName,
+          entity: registered.schema.entity,
+          traits: registered.schema.traits.map((t) => ({
+            name: t.name,
+            currentState: states[t.name],
+            states: t.states.map((s) => s.name),
+            events: [...new Set(t.transitions.map((tr) => tr.event))]
+          }))
+        }
+      });
+    });
+    router.post(
+      "/:orbital/events",
+      async (req, res, next) => {
+        try {
+          const orbitalName = req.params.orbital;
+          const firebaseUser = req.firebaseUser;
+          const user = firebaseUser ? {
+            uid: firebaseUser.uid,
+            email: firebaseUser.email,
+            displayName: firebaseUser.name,
+            ...firebaseUser
+          } : void 0;
+          const result = await this.processOrbitalEvent(orbitalName, {
+            ...req.body,
+            user
+          });
+          res.json(result);
+        } catch (error) {
+          next(error);
+        }
+      }
+    );
+    return router;
+  }
+  // ==========================================================================
+  // Direct API (for programmatic use)
+  // ==========================================================================
+  /**
+   * Get the event bus for manual event emission
+   */
+  getEventBus() {
+    return this.eventBus;
+  }
+  /**
+   * Get state for a specific orbital/trait
+   */
+  getState(orbitalName, traitName) {
+    const registered = this.orbitals.get(orbitalName);
+    if (!registered) return void 0;
+    if (traitName) {
+      return registered.manager.getState(traitName);
+    }
+    const states = {};
+    for (const [name, state] of registered.manager.getAllStates()) {
+      states[name] = state;
+    }
+    return states;
+  }
+  /**
+   * List registered orbitals
+   */
+  listOrbitals() {
+    return Array.from(this.orbitals.keys());
+  }
+  /**
+   * Check if an orbital is registered
+   */
+  hasOrbital(name) {
+    return this.orbitals.has(name);
+  }
+  /**
+   * Get information about active ticks
+   */
+  getActiveTicks() {
+    return this.tickBindings.map((binding) => ({
+      orbital: binding.orbitalName,
+      trait: binding.traitName,
+      tick: binding.tick.name,
+      interval: binding.tick.interval,
+      hasGuard: !!binding.tick.guard
+    }));
+  }
+};
+function createOrbitalServerRuntime(config) {
+  return new OrbitalServerRuntime(config);
+}
+
+export { OrbitalServerRuntime, createOrbitalServerRuntime };
+//# sourceMappingURL=OrbitalServerRuntime.js.map
+//# sourceMappingURL=OrbitalServerRuntime.js.map