@almadar/runtime 5.8.2 → 5.8.3

package/dist/OrbitalServerRuntime.js

@@ -1,1778 +1,4 @@
-import { createLogger, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, StateMachineManager, createContextFromBindings, validateEventPayload, formatPayloadValidationError, EffectExecutor } from './chunk-6XUD4OHN.js';
-export { InMemoryPersistence } from './chunk-6XUD4OHN.js';
+export { InMemoryPersistence, OrbitalServerRuntime, collectDeclaredConfigDefaults, createOrbitalServerRuntime } from './chunk-JO2SIC3Q.js';
 import './chunk-PZ5AY32C.js';
-import * as nodeModule from 'module';
-import { evaluateGuard, evaluate } from '@almadar/evaluator';
-import { isInlineTrait, isEntityCall } from '@almadar/core';
-
-var _resolvedNodeRequire = null;
-function nodeRequire(modulePath) {
-  if (!_resolvedNodeRequire) {
-    const evalRequire = (0, eval)('typeof require !== "undefined" ? require : null');
-    if (evalRequire) {
-      _resolvedNodeRequire = evalRequire;
-    } else {
-      const createReq = nodeModule.createRequire;
-      if (typeof createReq !== "function") {
-        throw new Error(
-          "[OrbitalServerRuntime] No synchronous require available. This branch is Node-only \u2014 invoking it from a browser indicates an isNodeEnv() guard regression upstream."
-        );
-      }
-      _resolvedNodeRequire = createReq(import.meta.url);
-    }
-  }
-  return _resolvedNodeRequire(modulePath);
-}
-var _nodeRequireExt = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
-var effectLog = createLogger("almadar:runtime:effects");
-var busLog = createLogger("almadar:runtime:bus");
-var renderLog = createLogger("almadar:runtime:render-ui");
-var xOrbitalLog = createLogger("almadar:runtime:cross-orbital");
-function isNodeEnv() {
-  return typeof process !== "undefined" && Boolean(process.versions?.node);
-}
-function collectDeclaredConfigDefaults(trait) {
-  if (!trait) return void 0;
-  const schema = trait.config;
-  if (!schema || typeof schema !== "object") return void 0;
-  const defaults = {};
-  let hasAny = false;
-  for (const [key, field] of Object.entries(schema)) {
-    if (field && typeof field === "object" && !Array.isArray(field) && "default" in field) {
-      const def = field.default;
-      if (def !== void 0) {
-        defaults[key] = def;
-        hasAny = true;
-      }
-    }
-  }
-  return hasAny ? defaults : void 0;
-}
-function needsPreprocessing(schema) {
-  for (const orbital of schema.orbitals) {
-    const uses = orbital.uses;
-    if (Array.isArray(uses) && uses.length > 0) {
-      return true;
-    }
-    const traits = orbital.traits ?? [];
-    for (const t of traits) {
-      if (!t || typeof t !== "object") continue;
-      const obj = t;
-      if (typeof obj.ref === "string" && obj.ref.includes(".") && !obj.stateMachine) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-var OrbitalServerRuntime = class {
-  orbitals = /* @__PURE__ */ new Map();
-  eventBus;
-  config;
-  persistence;
-  listenerCleanups = [];
-  tickBindings = [];
-  loader = null;
-  preprocessedCache = /* @__PURE__ */ new Map();
-  entitySharingMap = {};
-  eventNamespaceMap = {};
-  osHandlers = null;
-  localPersistence = null;
-  resolvedSchema = null;
-  constructor(config = {}) {
-    this.config = {
-      mode: "mock",
-      // Default to mock mode for preview
-      autoPreprocess: false,
-      namespaceEvents: true,
-      ...config
-    };
-    this.eventBus = new EventBus();
-    if (config.loaderConfig?.loader) {
-      this.loader = config.loaderConfig.loader;
-    } else if (config.loaderConfig?.stdLibPath) {
-      this.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();
-    }
-    if (config.localStorageRoot && isNodeEnv()) {
-      const { LocalPersistenceAdapter } = nodeRequire(`./LocalPersistenceAdapter${_nodeRequireExt}`);
-      this.localPersistence = new LocalPersistenceAdapter(config.localStorageRoot);
-    }
-    if (isNodeEnv()) {
-      const { createOsHandlers } = nodeRequire(`./createOsHandlers${_nodeRequireExt}`);
-      this.osHandlers = createOsHandlers({
-        emitEvent: (type, payload) => this.eventBus.emit(type, payload)
-      });
-    } else {
-      this.osHandlers = { handlers: {}, cleanup: () => {
-      } };
-    }
-    this.config.effectHandlers = {
-      ...this.osHandlers.handlers,
-      ...this.config.effectHandlers
-    };
-  }
-  /**
-   * Lazily construct a default loader when the caller didn't provide one
-   * but `register()` needs to preprocess. Looks for `@almadar/std` in the
-   * nearest `node_modules` so cross-orbital `std/behaviors/<name>` imports
-   * resolve to the tiered registry on disk.
-   *
-   * Node only — browsers should receive already-preprocessed schemas from
-   * their server.
-   */
-  async ensureLoader() {
-    if (this.loader) return;
-    if (typeof process === "undefined" || !process.versions?.node) {
-      return;
-    }
-    try {
-      const [{ fileURLToPath }, path, fs] = await Promise.all([
-        import('url'),
-        import('path'),
-        import('fs')
-      ]);
-      const mainEntryUrl = import.meta.resolve("@almadar/std");
-      const mainEntry = fileURLToPath(mainEntryUrl);
-      let stdLibPath = path.dirname(mainEntry);
-      while (stdLibPath !== path.dirname(stdLibPath)) {
-        if (fs.existsSync(path.join(stdLibPath, "package.json"))) {
-          const pkg = JSON.parse(
-            fs.readFileSync(path.join(stdLibPath, "package.json"), "utf-8")
-          );
-          if (pkg.name === "@almadar/std") break;
-        }
-        stdLibPath = path.dirname(stdLibPath);
-      }
-      const basePath = this.config.loaderConfig?.basePath ?? process.cwd();
-      this.loader = createUnifiedLoader({
-        basePath,
-        stdLibPath,
-        scopedPaths: this.config.loaderConfig?.scopedPaths
-      });
-      if (this.config.debug) {
-        console.log(
-          `[OrbitalRuntime] Default loader constructed: basePath=${basePath} stdLibPath=${stdLibPath}`
-        );
-      }
-    } catch (err) {
-      if (this.config.debug) {
-        console.warn(
-          `[OrbitalRuntime] Could not auto-construct loader: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-    }
-  }
-  // ==========================================================================
-  // Schema Registration
-  // ==========================================================================
-  /**
-   * Register an OrbitalSchema for execution.
-   *
-   * Auto-preprocesses the schema when it contains `uses` declarations or
-   * unresolved cross-orbital trait references (e.g. a trait with
-   * `ref: "Modal.traits.ModalRecordModal"` and no inline `stateMachine`).
-   * Without preprocessing, those refs arrive empty at the state machine and
-   * button clicks silently do nothing — see Phase 9.5.H.
-   *
-   * Preprocessing needs a loader. If `loaderConfig` is set, that loader is
-   * used. Otherwise, a default loader is constructed that points at
-   * `<cwd>` (for `basePath`) and the nearest `node_modules/@almadar/std` (for
-   * `stdLibPath`), which matches how every caller in this monorepo has the
-   * std registry on disk.
-   */
-  async register(schema) {
-    if (this.config.debug) {
-      console.log(`[OrbitalRuntime] Registering schema: ${schema.name}`);
-    }
-    if (needsPreprocessing(schema)) {
-      await this.ensureLoader();
-      if (this.loader) {
-        if (this.config.debug) {
-          console.log(`[OrbitalRuntime] Schema has uses/refs \u2014 auto-preprocessing`);
-        }
-        const result = await preprocessSchema(schema, {
-          basePath: this.config.loaderConfig?.basePath || process.cwd(),
-          stdLibPath: this.config.loaderConfig?.stdLibPath,
-          scopedPaths: this.config.loaderConfig?.scopedPaths,
-          loader: this.loader,
-          namespaceEvents: this.config.namespaceEvents
-        });
-        if (!result.success) {
-          throw new Error(
-            `Schema preprocessing failed: ${result.errors.join("; ")}`
-          );
-        }
-        schema = result.data.schema;
-        this.entitySharingMap = {
-          ...this.entitySharingMap,
-          ...result.data.entitySharing
-        };
-        this.eventNamespaceMap = {
-          ...this.eventNamespaceMap,
-          ...result.data.eventNamespaces
-        };
-      } else if (this.config.debug) {
-        console.warn(
-          `[OrbitalRuntime] Schema has uses/refs but no loader available \u2014 proceeding without preprocessing. Cross-orbital trait refs will be empty.`
-        );
-      }
-    }
-    for (const orbital of schema.orbitals) {
-      await this.registerOrbitalAsync(orbital);
-    }
-    this.setupEventListeners();
-    this.setupTicks();
-    this.resolvedSchema = schema;
-  }
-  /**
-   * Register an OrbitalSchema synchronously (for backward compatibility).
-   * Note: This version doesn't wait for instance seeding to complete.
-   * Use async register() for guaranteed instance seeding.
-   */
-  registerSync(schema) {
-    if (this.config.debug) {
-      console.log(`[OrbitalRuntime] Registering schema (sync): ${schema.name}`);
-    }
-    for (const orbital of schema.orbitals) {
-      this.registerOrbital(orbital);
-    }
-    this.setupEventListeners();
-    this.setupTicks();
-    this.resolvedSchema = schema;
-  }
-  /**
-   * Returns the schema that this runtime is currently executing, post-
-   * preprocessing. Safe to expose from an HTTP `/api/schema` endpoint — every
-   * cross-orbital trait ref will have an inline `stateMachine` already, which
-   * is what the browser's `schema-to-ir` resolver needs to wire button clicks
-   * back to state transitions.
-   *
-   * Returns `null` if `register()` hasn't run yet.
-   */
-  getResolvedSchema() {
-    return this.resolvedSchema;
-  }
-  /**
-   * One-call entry point: read an `.orb` file from disk, parse it, preprocess
-   * cross-orbital imports, and register the result. Callers never touch raw
-   * `.orb` bytes — `register()` handles preprocessing internally.
-   *
-   * Node only. Browsers must receive already-resolved schemas from their
-   * server (see `getResolvedSchema()`).
-   */
-  async registerFromFile(path) {
-    if (typeof process === "undefined" || !process.versions?.node) {
-      throw new Error(
-        "registerFromFile is Node-only. Browsers should receive resolved schemas from their server."
-      );
-    }
-    const { readFile } = await import('fs/promises');
-    const raw = await readFile(path, "utf-8");
-    let schema;
-    try {
-      schema = JSON.parse(raw);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`registerFromFile: ${path} is not valid JSON: ${msg}`);
-    }
-    await this.register(schema);
-  }
-  /**
-   * 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
-   */
-  async registerOrbitalAsync(orbital) {
-    const configByTrait = /* @__PURE__ */ new Map();
-    const unwrapped = (orbital.traits || []).map((t) => {
-      if (t && typeof t === "object" && "ref" in t && "_resolved" in t) {
-        const wrapper = t;
-        const inner = wrapper._resolved;
-        if (wrapper.config && inner?.name) {
-          configByTrait.set(inner.name, wrapper.config);
-        }
-        return inner;
-      }
-      return t;
-    });
-    const inlineTraits = unwrapped.filter(isInlineTrait);
-    const traitDefs = inlineTraits.map((t) => {
-      const sm = t.stateMachine;
-      const states = sm?.states || [];
-      const transitions = sm?.transitions || [];
-      return {
-        name: t.name,
-        states,
-        transitions,
-        listens: t.listens
-      };
-    });
-    const manager = new StateMachineManager(traitDefs, {
-      contextExtensions: this.config.contextExtensions
-    });
-    for (const [traitName, traitConfig] of configByTrait) {
-      manager.setTraitConfig(traitName, traitConfig);
-    }
-    const entityRef = orbital.entity;
-    let entity;
-    if (typeof entityRef === "string") {
-      entity = { name: entityRef, fields: [] };
-    } else if (isEntityCall(entityRef)) {
-      const fallbackName = entityRef.name ?? entityRef.extends.replace(/\.entity$/, "");
-      entity = {
-        name: fallbackName,
-        fields: entityRef.fields ?? [],
-        ...entityRef.persistence ? { persistence: entityRef.persistence } : {},
-        ...entityRef.collection ? { collection: entityRef.collection } : {}
-      };
-    } else {
-      entity = entityRef;
-    }
-    this.orbitals.set(orbital.name, {
-      schema: orbital,
-      entity,
-      traits: inlineTraits,
-      configByTrait,
-      manager,
-      entityData: /* @__PURE__ */ new Map()
-    });
-    if (entity?.name && entity.instances && Array.isArray(entity.instances)) {
-      const instances = entity.instances;
-      if (instances.length > 0) {
-        console.log(`[OrbitalRuntime] Seeding ${instances.length} instances for ${entity.name} from schema`);
-        const results = await Promise.all(
-          instances.map(async (instance) => {
-            try {
-              const result = await this.persistence.create(entity.name, instance);
-              console.log(`[OrbitalRuntime] Seeded instance: ${instance.id || "no-id"}`);
-              return result;
-            } catch (err) {
-              console.error(`[OrbitalRuntime] Failed to seed instance ${instance.id}:`, err);
-              return null;
-            }
-          })
-        );
-        const successCount = results.filter((r) => r !== null).length;
-        console.log(`[OrbitalRuntime] Seeded ${successCount}/${instances.length} ${entity.name} instances from schema`);
-      }
-    } else if (this.config.mode === "mock" && this.persistence instanceof MockPersistenceAdapter) {
-      if (this.config.debug) {
-        console.log(`[OrbitalRuntime] No instances in schema, generating mock data for ${entity?.name}`);
-      }
-      if (entity?.name && entity.fields) {
-        const fields = entity.fields.filter(
-          (f) => typeof f.name === "string" && f.name.length > 0
-        ).map((f) => ({
-          name: f.name,
-          type: f.type,
-          required: f.required,
-          values: f.values,
-          default: f.default
-        }));
-        this.persistence.registerEntity({ name: entity.name, fields });
-        if (this.config.debug) {
-          console.log(`[OrbitalRuntime] Seeded mock data for entity: ${entity.name}, count: ${this.persistence.count(entity.name)}`);
-        }
-      }
-    }
-    if (this.config.debug) {
-      console.log(
-        `[OrbitalRuntime] Registered orbital: ${orbital.name} with ${(orbital.traits || []).length} trait(s)`
-      );
-    }
-  }
-  /**
-   * Register a single orbital (sync wrapper for backward compatibility)
-   */
-  registerOrbital(orbital) {
-    this.registerOrbitalAsync(orbital).catch((err) => {
-      console.error(`[OrbitalRuntime] Failed to register orbital:`, err);
-    });
-  }
-  /**
-   * 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.traits) {
-        if (!trait.listens) continue;
-        for (const listener of trait.listens) {
-          const { bareEvent, matcher } = parseListenSource(listener, orbitalName);
-          const cleanup = this.eventBus.on(bareEvent, async (event) => {
-            if (!matcher(event.source)) return;
-            if (this.config.debug) {
-              console.log(
-                `[OrbitalRuntime] ${orbitalName}.${trait.name} received: ${listener.event} (from ${event.source?.orbital ?? "?"}.${event.source?.trait ?? "?"})`
-              );
-            }
-            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;
-                }
-              }
-            }
-            const raw = event.payload;
-            const mapped = mappedPayload;
-            const pickId = (field) => mapped?.[field] ?? raw?.[field];
-            const forwardedEntityId = pickId("entityId") ?? pickId("orbitalName");
-            await this.processOrbitalEvent(orbitalName, {
-              event: listener.triggers,
-              payload: mappedPayload,
-              entityId: forwardedEntityId
-            });
-          });
-          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.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.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"
-            }, false, this.config.contextExtensions);
-            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();
-    if (this.persistence instanceof MockPersistenceAdapter) {
-      this.persistence.clearAll();
-    }
-    if (this.osHandlers) {
-      this.osHandlers.cleanup();
-      this.osHandlers = null;
-    }
-  }
-  /**
-   * Reset the mock persistence store to a clean-slate re-seed without
-   * unregistering orbitals. Exposed for verifier tools that want to
-   * start each test with deterministic seeded rows, not the residue of
-   * the previous walk's persist-creates. No-op when the persistence
-   * layer is not MockPersistenceAdapter.
-   */
-  resetMockPersistence() {
-    if (!(this.persistence instanceof MockPersistenceAdapter)) return;
-    busLog.debug("mock:reset:enter", {
-      orbitalCount: this.orbitals.size,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    this.persistence.clearAll();
-    for (const registered of this.orbitals.values()) {
-      const entity = registered.entity;
-      if (entity?.name && entity.fields) {
-        const fields = entity.fields.filter(
-          (f) => typeof f.name === "string" && f.name.length > 0
-        ).map((f) => ({
-          name: f.name,
-          type: f.type,
-          required: f.required,
-          values: f.values,
-          default: f.default
-        }));
-        this.persistence.registerEntity({ name: entity.name, fields });
-      }
-    }
-  }
-  // ==========================================================================
-  // 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 payloadRow = request.payload?.["row"];
-    const payloadRowAsPayload = payloadRow !== null && typeof payloadRow === "object" && !Array.isArray(payloadRow) ? payloadRow : void 0;
-    const payloadRowId = payloadRowAsPayload?.["id"];
-    renderLog.debug("processOrbitalEvent:enter", {
-      orbital: orbitalName,
-      event: request.event,
-      hasPayloadRow: payloadRowAsPayload !== void 0,
-      payloadRowId: typeof payloadRowId === "string" || typeof payloadRowId === "number" ? payloadRowId : void 0,
-      entityId: request.entityId
-    });
-    busLog.debug("bus:incoming", {
-      orbital: orbitalName,
-      event: request.event,
-      payload: JSON.stringify(request.payload ?? null),
-      entityId: request.entityId,
-      traitStates: JSON.stringify(
-        Array.from(registered.manager.getAllStates().entries()).map(([traitName, state]) => ({
-          traitName,
-          currentState: state.currentState
-        }))
-      )
-    });
-    xOrbitalLog.info("processOrbitalEvent:enter", {
-      orbital: orbitalName,
-      event: request.event,
-      traitsInOrbital: registered.traits.map((t) => t.name).join(","),
-      payloadActiveTraits: JSON.stringify(
-        request.payload?.["_activeTraits"] ?? null
-      )
-    });
-    const { event, payload, entityId, user } = request;
-    const validationFailures = [];
-    for (const trait of registered.traits) {
-      const eventSchema = trait.stateMachine?.events?.find((e) => e.key === event);
-      if (eventSchema?.payloadSchema && eventSchema.payloadSchema.length > 0) {
-        validationFailures.push(
-          ...validateEventPayload(event, payload, eventSchema.payloadSchema)
-        );
-      }
-    }
-    if (validationFailures.length > 0) {
-      return {
-        success: false,
-        transitioned: false,
-        states: {},
-        emittedEvents: [],
-        error: formatPayloadValidationError(validationFailures)
-      };
-    }
-    const emittedEvents = [];
-    const fetchedData = {};
-    const clientEffects = [];
-    const clientEffectsByTrait = [];
-    const effectResults = [];
-    const activeTraits = payload?._activeTraits;
-    const cleanPayload = payload ? { ...payload } : void 0;
-    if (cleanPayload) {
-      delete cleanPayload._activeTraits;
-    }
-    let entityData = {};
-    if (entityId) {
-      const stored = await this.persistence.getById(
-        registered.entity.name,
-        entityId
-      );
-      if (stored) {
-        entityData = stored;
-      }
-    } else if (registered.entity?.name) {
-      try {
-        const all = await this.persistence.list(registered.entity.name);
-        if (Array.isArray(all) && all.length > 0 && all[0]) {
-          entityData = all[0];
-        }
-      } catch {
-      }
-    }
-    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,
-          clientEffectsByTrait
-        );
-      }
-    }
-    const states = {};
-    for (const [name, state] of registered.manager.getAllStates()) {
-      states[name] = state.currentState;
-    }
-    const response = {
-      success: true,
-      transitioned: results.length > 0,
-      states,
-      emittedEvents
-    };
-    if (clientEffects.length > 0) {
-      response.clientEffects = clientEffects;
-    }
-    if (clientEffectsByTrait.length > 0) {
-      response.clientEffectsByTrait = clientEffectsByTrait;
-    }
-    if (effectResults.length > 0) {
-      response.effectResults = effectResults;
-    }
-    return response;
-  }
-  /**
-   * Execute effects from a transition
-   */
-  async executeEffects(registered, traitName, effects, payload, entityData, entityId, emittedEvents, fetchedData, clientEffects, effectResults, user, clientEffectsByTrait) {
-    const entityType = registered.entity.name;
-    const pushClientEffect = (effect) => {
-      clientEffects.push(effect);
-      clientEffectsByTrait?.push({ traitName, effect });
-    };
-    let bindingsRef = null;
-    let contextRef = null;
-    const handlers = {
-      emit: (event, eventPayload, source) => {
-        if (this.config.debug) {
-          console.log(`[OrbitalRuntime] Emitting: ${event}`, eventPayload, source);
-        }
-        const stamp = source ?? {
-          orbital: registered.schema.name,
-          trait: traitName
-        };
-        this.eventBus.emit(event, eventPayload, stamp);
-        emittedEvents.push({ event, payload: eventPayload, source: stamp });
-        effectLog.debug("emit:push", {
-          event,
-          cumulativeEmittedCount: emittedEvents.length,
-          sourceTrait: stamp.trait,
-          sourceOrbital: stamp.orbital
-        });
-        xOrbitalLog.info("emit:server", {
-          event,
-          sourceOrbital: stamp.orbital,
-          sourceTrait: stamp.trait,
-          dispatchOrbital: registered.schema.name
-        });
-      },
-      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) => {
-        if (action === "batch") {
-          const operations = data?.operations;
-          if (!Array.isArray(operations) || operations.length === 0) {
-            effectResults.push({
-              effect: "persist",
-              action: "batch",
-              success: false,
-              error: "Batch requires a non-empty operations array"
-            });
-            return;
-          }
-          const batchResults = [];
-          const completed = [];
-          let batchFailed = false;
-          let batchError = "";
-          for (const op of operations) {
-            if (!Array.isArray(op) || op.length < 2) {
-              batchFailed = true;
-              batchError = `Invalid batch operation format: ${JSON.stringify(op)}`;
-              break;
-            }
-            const [opAction, opEntityType, ...opRest] = op;
-            try {
-              switch (opAction) {
-                case "create": {
-                  const createData = opRest[0] || {};
-                  const { id: newId } = await this.persistence.create(opEntityType, createData);
-                  batchResults.push({ action: "create", entityType: opEntityType, id: newId, ...createData });
-                  completed.push({ action: "create", entityType: opEntityType, id: newId });
-                  break;
-                }
-                case "update": {
-                  const updateId = opRest[0];
-                  const updateData = opRest[1] || {};
-                  await this.persistence.update(opEntityType, updateId, updateData);
-                  const updated = await this.persistence.getById(opEntityType, updateId);
-                  batchResults.push({ action: "update", entityType: opEntityType, id: updateId, ...updated || updateData });
-                  completed.push({ action: "update", entityType: opEntityType, id: updateId });
-                  break;
-                }
-                case "delete": {
-                  const deleteId = opRest[0];
-                  await this.persistence.delete(opEntityType, deleteId);
-                  batchResults.push({ action: "delete", entityType: opEntityType, id: deleteId, deleted: true });
-                  completed.push({ action: "delete", entityType: opEntityType, id: deleteId });
-                  break;
-                }
-                default:
-                  batchFailed = true;
-                  batchError = `Unknown batch operation action: ${opAction}`;
-                  break;
-              }
-            } catch (err) {
-              batchFailed = true;
-              batchError = `Batch operation [${opAction}, ${opEntityType}] failed: ${err instanceof Error ? err.message : String(err)}`;
-              break;
-            }
-            if (batchFailed) break;
-          }
-          effectResults.push({
-            effect: "persist",
-            action: "batch",
-            data: {
-              operations: batchResults,
-              completedCount: completed.length,
-              totalCount: operations.length
-            },
-            success: !batchFailed,
-            ...batchFailed ? { error: batchError } : {}
-          });
-          return;
-        }
-        const type = targetEntityType || entityType;
-        let resultData;
-        const sizeBefore = (await this.persistence.list(type)).length;
-        try {
-          if (action === "create" || action === "update") {
-            this.validateRelationCardinality(type, data || {});
-          }
-          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": {
-              const directId = typeof data === "string" ? data : void 0;
-              const nestedId = typeof data === "object" && data !== null ? data.id : void 0;
-              const deleteId = directId ?? nestedId ?? entityId;
-              if (deleteId) {
-                await this.enforceOnDeleteRules(type, deleteId);
-                await this.persistence.delete(type, deleteId);
-                resultData = { id: deleteId, deleted: true };
-              }
-              break;
-            }
-          }
-          const sizeAfter = (await this.persistence.list(type)).length;
-          effectLog.debug("persist:store-mutate", {
-            action,
-            entityType: type,
-            resultId: resultData?.id,
-            sizeBefore,
-            sizeAfter,
-            delta: sizeAfter - sizeBefore
-          });
-          effectResults.push({
-            effect: "persist",
-            action,
-            entityType: type,
-            data: resultData,
-            success: true
-          });
-        } catch (err) {
-          effectLog.error("persist:store-mutate-error", {
-            action,
-            entityType: type,
-            error: err instanceof Error ? err.message : String(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 {
-          let result = null;
-          if (options?.id) {
-            const entity = await this.persistence.getById(fetchEntityType, options.id);
-            if (entity) {
-              if (options?.include && options.include.length > 0) {
-                await this.populateRelations([entity], fetchEntityType, options.include);
-              }
-              fetchedData[fetchEntityType] = [entity];
-              result = 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);
-            }
-            if (options?.include && options.include.length > 0) {
-              await this.populateRelations(entities, fetchEntityType, options.include);
-            }
-            fetchedData[fetchEntityType] = entities;
-            result = entities;
-          }
-          if (bindingsRef && result) {
-            const records = Array.isArray(result) ? result : [result];
-            if (records.length > 0) {
-              const merged = Object.assign([...records], records[0]);
-              bindingsRef[fetchEntityType] = merged;
-              if (fetchEntityType === entityType) {
-                bindingsRef.entity = merged;
-              }
-            }
-          }
-          return result;
-        } catch (error) {
-          console.error(`[OrbitalRuntime] Fetch error for ${fetchEntityType}:`, error);
-          return null;
-        }
-      },
-      // Resource operators: ref, deref, swap, watch, atomic
-      ref: async (refEntityType, options) => {
-        try {
-          return await handlers.fetch(refEntityType, options);
-        } catch (error) {
-          console.error(`[OrbitalRuntime] ref error for ${refEntityType}:`, error);
-          return null;
-        }
-      },
-      deref: async (derefEntityType, options) => {
-        try {
-          let result = null;
-          if (options?.id) {
-            const entity = await this.persistence.getById(derefEntityType, options.id);
-            if (entity) {
-              fetchedData[derefEntityType] = [entity];
-              result = entity;
-            }
-          } else {
-            const entities = await this.persistence.list(derefEntityType);
-            fetchedData[derefEntityType] = entities;
-            result = entities;
-          }
-          if (bindingsRef && result) {
-            const records = Array.isArray(result) ? result : [result];
-            if (records.length > 0) {
-              const merged = Object.assign([...records], records[0]);
-              bindingsRef[derefEntityType] = merged;
-              if (derefEntityType === entityType) {
-                bindingsRef.entity = merged;
-              }
-            }
-          }
-          effectResults.push({
-            effect: "deref",
-            entityType: derefEntityType,
-            success: true
-          });
-          return result;
-        } catch (error) {
-          effectResults.push({
-            effect: "deref",
-            entityType: derefEntityType,
-            success: false,
-            error: error instanceof Error ? error.message : String(error)
-          });
-          return null;
-        }
-      },
-      swap: async (swapEntityType, swapEntityId, transform) => {
-        try {
-          const current = await this.persistence.getById(swapEntityType, swapEntityId);
-          if (!current) {
-            effectResults.push({
-              effect: "swap",
-              entityType: swapEntityType,
-              success: false,
-              error: `Entity ${swapEntityType}/${swapEntityId} not found`
-            });
-            return null;
-          }
-          const ctx = createContextFromBindings({
-            current,
-            entity: entityData,
-            payload
-          }, false, this.config.contextExtensions);
-          let newData;
-          if (Array.isArray(transform)) {
-            const result = evaluate(
-              transform,
-              ctx
-            );
-            if (result && typeof result === "object" && !Array.isArray(result)) {
-              newData = result;
-            } else {
-              newData = current;
-            }
-          } else if (typeof transform === "object" && transform !== null) {
-            newData = { ...current, ...transform };
-          } else {
-            effectResults.push({
-              effect: "swap",
-              entityType: swapEntityType,
-              success: false,
-              error: "swap! transform must be an S-expression or object"
-            });
-            return null;
-          }
-          await this.persistence.update(swapEntityType, swapEntityId, newData);
-          effectResults.push({
-            effect: "swap",
-            entityType: swapEntityType,
-            data: { id: swapEntityId, ...newData },
-            success: true
-          });
-          return newData;
-        } catch (error) {
-          effectResults.push({
-            effect: "swap",
-            entityType: swapEntityType,
-            success: false,
-            error: error instanceof Error ? error.message : String(error)
-          });
-          return null;
-        }
-      },
-      watch: (_watchEntityType, _watchOptions) => {
-        if (this.config.debug) {
-          console.log(`[OrbitalRuntime] watch is a no-op on server: ${_watchEntityType}`);
-        }
-      },
-      atomic: async (atomicEffects) => {
-        let atomicFailed = false;
-        let atomicError = "";
-        const atomicExecutor = new EffectExecutor({
-          handlers,
-          bindings: bindingsRef ?? {},
-          context: contextRef ?? { traitName, orbitalName: registered.schema.name, state: "unknown", transition: "unknown" },
-          debug: this.config.debug,
-          contextExtensions: this.config.contextExtensions
-        });
-        for (const innerEffect of atomicEffects) {
-          if (atomicFailed) break;
-          try {
-            await atomicExecutor.execute(innerEffect);
-          } catch (err) {
-            atomicFailed = true;
-            atomicError = err instanceof Error ? err.message : String(err);
-          }
-        }
-        if (atomicFailed) {
-          effectResults.push({
-            effect: "atomic",
-            success: false,
-            error: `Atomic block failed: ${atomicError}`
-          });
-        } else {
-          effectResults.push({
-            effect: "atomic",
-            success: true,
-            data: { innerCount: atomicEffects.length }
-          });
-        }
-      },
-      // Client-side effects - collect for forwarding to client
-      renderUI: (slot, pattern, props, priority) => {
-        const patternNode = pattern !== null && typeof pattern === "object" && !Array.isArray(pattern) ? pattern : null;
-        const patternEntity = patternNode?.entity;
-        const entityRow = patternEntity !== null && typeof patternEntity === "object" && !Array.isArray(patternEntity) ? patternEntity : null;
-        const patternTypeRaw = patternNode?.["type"];
-        renderLog.debug("renderUI:push", {
-          trait: traitName,
-          slot,
-          patternType: typeof patternTypeRaw === "string" ? patternTypeRaw : void 0,
-          entityRowId: typeof entityRow?.id === "string" ? entityRow.id : void 0,
-          entityIsObject: entityRow !== null
-        });
-        pushClientEffect(["render-ui", slot, pattern, props, priority]);
-      },
-      navigate: (path, params) => {
-        pushClientEffect(["navigate", path, params]);
-      },
-      notify: (message, type) => {
-        if (this.config.debug) {
-          console.log(`[OrbitalRuntime] Notification (${type}): ${message}`);
-        }
-        pushClientEffect(["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 declaredDefaults = collectDeclaredConfigDefaults(
-      registered.traits.find((t) => t.name === traitName)
-    );
-    const callSiteOverride = registered.configByTrait.get(traitName);
-    if (declaredDefaults || callSiteOverride) {
-      bindings.config = { ...declaredDefaults ?? {}, ...callSiteOverride ?? {} };
-    }
-    if (entityType) {
-      bindings[entityType] = entityData;
-    }
-    bindingsRef = bindings;
-    const context = {
-      traitName,
-      orbitalName: registered.schema.name,
-      state: state?.currentState || "unknown",
-      transition: "unknown",
-      entityId
-    };
-    contextRef = context;
-    const executor = new EffectExecutor({
-      handlers,
-      bindings,
-      context,
-      debug: this.config.debug,
-      contextExtensions: this.config.contextExtensions
-    });
-    await executor.executeAll(effects);
-  }
-  // ==========================================================================
-  // Relation Population
-  // ==========================================================================
-  /**
-   * Populate relation fields on entities
-   *
-   * For each field in `include`, find the relation field configuration and
-   * fetch the related entity, attaching it to the parent entity.
-   *
-   * @param entities - Entities to populate
-   * @param entityType - Entity type name
-   * @param include - Relation field names to populate
-   */
-  /**
-   * Validate that relation field values match their declared cardinality.
-   * Called before create/update to ensure data integrity.
-   */
-  validateRelationCardinality(entityType, data) {
-    for (const [, registered] of this.orbitals) {
-      if (registered.entity.name !== entityType) continue;
-      for (const field of registered.entity.fields ?? []) {
-        if (field.type !== "relation") continue;
-        if (field.name === void 0) continue;
-        const fieldName = field.name;
-        const value = data[fieldName];
-        if (value === void 0 || value === null) continue;
-        const cardinality = field.relation?.cardinality || "one";
-        if (cardinality === "one" || cardinality === "many-to-one") {
-          if (Array.isArray(value)) {
-            throw new Error(
-              `Cardinality violation: ${entityType}.${fieldName} has cardinality '${cardinality}' but received an array. Expected a single string ID.`
-            );
-          }
-        } else if (cardinality === "many" || cardinality === "many-to-many" || cardinality === "one-to-many") {
-          if (typeof value === "string") {
-            data[fieldName] = [value];
-          } else if (Array.isArray(value)) {
-            const nonStrings = value.filter((v) => typeof v !== "string");
-            if (nonStrings.length > 0) {
-              throw new Error(
-                `Cardinality violation: ${entityType}.${fieldName} has cardinality '${cardinality}' but array contains non-string values.`
-              );
-            }
-          }
-        }
-      }
-      break;
-    }
-  }
-  /**
-   * Enforce onDelete rules for relation fields pointing to the entity being deleted.
-   * Scans all registered entities for relation fields targeting the given entity type,
-   * finds records referencing the ID being deleted, and applies cascade/nullify/restrict.
-   */
-  async enforceOnDeleteRules(entityType, deletedId) {
-    for (const [, registered] of this.orbitals) {
-      const entity = registered.entity;
-      const fields = entity.fields ?? [];
-      for (const field of fields) {
-        if (field.type !== "relation") continue;
-        if (field.relation?.entity !== entityType) continue;
-        if (field.name === void 0) continue;
-        const fieldName = field.name;
-        const onDelete = field.relation.onDelete || "restrict";
-        const referringEntityType = entity.name;
-        const allRecords = await this.persistence.list(referringEntityType);
-        const affectedRecords = allRecords.filter((record) => {
-          const fkValue = record[fieldName];
-          if (typeof fkValue === "string") return fkValue === deletedId;
-          if (Array.isArray(fkValue)) return fkValue.includes(deletedId);
-          return false;
-        });
-        if (affectedRecords.length === 0) continue;
-        switch (onDelete) {
-          case "restrict":
-            throw new Error(
-              `Cannot delete ${entityType} ${deletedId}: ${affectedRecords.length} ${referringEntityType} record(s) reference it via ${field.name}. Rule: restrict.`
-            );
-          case "cascade":
-            for (const record of affectedRecords) {
-              const recordId = record.id;
-              if (recordId) {
-                await this.persistence.delete(referringEntityType, recordId);
-              }
-            }
-            if (this.config.debug) {
-              console.log(`[OrbitalRuntime] Cascade deleted ${affectedRecords.length} ${referringEntityType} records`);
-            }
-            break;
-          case "nullify":
-            for (const record of affectedRecords) {
-              const recordId = record.id;
-              if (recordId && field.name !== void 0) {
-                const fieldName2 = field.name;
-                const update = {};
-                const fkValue = record[fieldName2];
-                if (Array.isArray(fkValue)) {
-                  update[fieldName2] = fkValue.filter((id) => id !== deletedId);
-                } else {
-                  update[fieldName2] = null;
-                }
-                await this.persistence.update(referringEntityType, recordId, update);
-              }
-            }
-            if (this.config.debug) {
-              console.log(`[OrbitalRuntime] Nullified ${field.name} on ${affectedRecords.length} ${referringEntityType} records`);
-            }
-            break;
-        }
-      }
-    }
-  }
-  async populateRelations(entities, entityType, include, depth = 0, visited = /* @__PURE__ */ new Set()) {
-    const maxDepth = 2;
-    if (depth >= maxDepth || visited.has(entityType)) {
-      if (this.config.debug) {
-        console.log(`[OrbitalRuntime] Skipping populateRelations for ${entityType}: depth=${depth}, visited=${visited.has(entityType)}`);
-      }
-      return;
-    }
-    visited.add(entityType);
-    let entityFields;
-    for (const [, registered] of this.orbitals) {
-      if (registered.entity.name === entityType) {
-        entityFields = registered.entity.fields.filter(
-          (f) => typeof f.name === "string" && f.name.length > 0
-        );
-        break;
-      }
-    }
-    if (!entityFields) {
-      if (this.config.debug) {
-        console.warn(`[OrbitalRuntime] No entity definition found for ${entityType}`);
-      }
-      return;
-    }
-    for (const includeField of include) {
-      const relationField = entityFields.find((f) => {
-        if (f.type !== "relation") return false;
-        return f.name === includeField || f.name === `${includeField}Id` || f.name.replace(/Id$/, "") === includeField;
-      });
-      if (!relationField?.relation?.entity) {
-        if (this.config.debug) {
-          console.warn(`[OrbitalRuntime] No relation field found for '${includeField}' on ${entityType}`);
-        }
-        continue;
-      }
-      const foreignKeyField = relationField.name;
-      const relatedEntityType = relationField.relation.entity;
-      const cardinality = relationField.relation.cardinality || "one";
-      const foreignKeyIds = /* @__PURE__ */ new Set();
-      for (const entity of entities) {
-        const fkValue = entity[foreignKeyField];
-        if (fkValue && typeof fkValue === "string") {
-          foreignKeyIds.add(fkValue);
-        } else if (Array.isArray(fkValue)) {
-          for (const id of fkValue) {
-            if (id && typeof id === "string") {
-              foreignKeyIds.add(id);
-            }
-          }
-        }
-      }
-      if (foreignKeyIds.size === 0) continue;
-      const relatedEntities = /* @__PURE__ */ new Map();
-      for (const fkId of foreignKeyIds) {
-        try {
-          const related = await this.persistence.getById(relatedEntityType, fkId);
-          if (related) {
-            relatedEntities.set(fkId, related);
-          }
-        } catch (error) {
-          if (this.config.debug) {
-            console.error(`[OrbitalRuntime] Error fetching related ${relatedEntityType}:`, error);
-          }
-        }
-      }
-      const populatedFieldName = includeField.endsWith("Id") ? includeField.slice(0, -2) : includeField;
-      for (const entity of entities) {
-        const fkValue = entity[foreignKeyField];
-        if (cardinality === "one" || cardinality === "many-to-one") {
-          if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
-            Object.defineProperty(entity, populatedFieldName, {
-              value: relatedEntities.get(fkValue),
-              writable: true,
-              enumerable: true,
-              configurable: true
-            });
-          }
-        } else {
-          if (Array.isArray(fkValue)) {
-            const fkIds = fkValue.filter((id) => typeof id === "string");
-            Object.defineProperty(entity, populatedFieldName, {
-              value: fkIds.map((id) => relatedEntities.get(id)).filter(Boolean),
-              writable: true,
-              enumerable: true,
-              configurable: true
-            });
-          } else if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
-            Object.defineProperty(entity, populatedFieldName, {
-              value: [relatedEntities.get(fkValue)],
-              writable: true,
-              enumerable: true,
-              configurable: true
-            });
-          }
-        }
-      }
-      if (this.config.debug) {
-        console.log(`[OrbitalRuntime] Populated '${populatedFieldName}' on ${entities.length} ${entityType} entities`);
-      }
-    }
-  }
-  // ==========================================================================
-  // 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() {
-    if (!isNodeEnv()) {
-      throw new Error(
-        "OrbitalServerRuntime.router() is Node-only (uses Express). For in-browser use, mount <BrowserPlayground> from @almadar/ui instead."
-      );
-    }
-    const { Router } = nodeRequire("express");
-    const router = Router();
-    router.get("/", (_req, res) => {
-      const orbitals = Array.from(this.orbitals.entries()).map(
-        ([name, reg]) => ({
-          name,
-          entity: reg.entity?.name,
-          traits: (reg.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.entity,
-          traits: registered.traits.map((t) => ({
-            name: t.name,
-            currentState: states[t.name],
-            states: (t.stateMachine?.states || []).map((s) => s.name),
-            events: [...new Set((t.stateMachine?.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 ? {
-            ...firebaseUser,
-            displayName: firebaseUser.name ?? firebaseUser.displayName
-          } : 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);
-}
-function parseListenSource(listener, listenerOrbital) {
-  const explicit = listener.source;
-  if (explicit && typeof explicit === "object") {
-    return {
-      bareEvent: listener.event,
-      matcher: buildMatcher(explicit, listenerOrbital)
-    };
-  }
-  const key = listener.event;
-  const parts = key.split(".");
-  if (parts.length === 1) {
-    return { bareEvent: key, matcher: () => true };
-  }
-  if (parts.length === 2) {
-    const [sourceOrStar, eventName] = parts;
-    if (sourceOrStar === "*") {
-      return { bareEvent: eventName, matcher: () => true };
-    }
-    return {
-      bareEvent: eventName,
-      matcher: buildMatcher(
-        { kind: "trait", trait: sourceOrStar },
-        listenerOrbital
-      )
-    };
-  }
-  if (parts.length >= 3) {
-    const eventName = parts[parts.length - 1];
-    const trait = parts[parts.length - 2];
-    const orbital = parts.slice(0, parts.length - 2).join(".");
-    return {
-      bareEvent: eventName,
-      matcher: buildMatcher({ kind: "orbital", orbital, trait }, listenerOrbital)
-    };
-  }
-  return { bareEvent: key, matcher: () => true };
-}
-function buildMatcher(src, listenerOrbital) {
-  if (src.kind === "any") return () => true;
-  if (src.kind === "trait") {
-    const wantedTrait2 = src.trait;
-    return (source) => !!source && source.orbital === listenerOrbital && source.trait === wantedTrait2;
-  }
-  const wantedOrbital = src.orbital;
-  const wantedTrait = src.trait;
-  return (source) => !!source && source.orbital === wantedOrbital && source.trait === wantedTrait;
-}
-
-export { OrbitalServerRuntime, createOrbitalServerRuntime };
 //# sourceMappingURL=OrbitalServerRuntime.js.map
 //# sourceMappingURL=OrbitalServerRuntime.js.map