@almadar/runtime 6.9.2 → 6.9.4

package/dist/OrbitalServerRuntime.js

@@ -1,4 +1,1855 @@
-export { InMemoryPersistence, OrbitalServerRuntime, collectDeclaredConfigDefaults, createOrbitalServerRuntime } from './chunk-VUXJJPIQ.js';
+import { EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, StateMachineManager, createContextFromBindings, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, EffectExecutor } from './chunk-R6Y4IJ7I.js';
+export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-R6Y4IJ7I.js';
 import './chunk-PZ5AY32C.js';
+import { createLogger } from '@almadar/logger';
+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");
+var persistLog = createLogger("almadar:runtime:persist");
+var registerLog = createLogger("almadar:runtime:register");
+var dynamicLog = createLogger("almadar:runtime:dynamic");
+function isNodeEnv() {
+  return typeof process !== "undefined" && Boolean(process.versions?.node);
+}
+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) {
+        persistLog.debug("mock:init", { adapter: "MockPersistenceAdapter" });
+      }
+    } 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) {
+        registerLog.debug("loader:constructed", { basePath, stdLibPath });
+      }
+    } catch (err) {
+      if (this.config.debug) {
+        registerLog.warn("loader:construct-failed", { error: err instanceof Error ? err : 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) {
+      registerLog.debug("register:schema", { name: schema.name });
+    }
+    if (needsPreprocessing(schema)) {
+      await this.ensureLoader();
+      if (this.loader) {
+        if (this.config.debug) {
+          registerLog.debug("register:auto-preprocessing", { name: schema.name });
+        }
+        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) {
+        registerLog.warn("register:no-loader", { name: schema.name });
+      }
+    }
+    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) {
+      registerLog.debug("register:schema-sync", { name: 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) {
+        registerLog.debug("preprocess:cache-hit", { name: 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) {
+      registerLog.debug("preprocess:start", { name: 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(),
+      traitFieldStates: /* @__PURE__ */ new Map()
+    });
+    if (entity?.name && entity.instances && Array.isArray(entity.instances)) {
+      const instances = entity.instances;
+      if (instances.length > 0) {
+        persistLog.debug("seed:start", { entity: entity.name, count: instances.length });
+        const results = await Promise.all(
+          instances.map(async (instance) => {
+            try {
+              const result = await this.persistence.create(entity.name, instance);
+              persistLog.debug("seed:instance", { entity: entity.name, id: instance.id ?? "no-id" });
+              return result;
+            } catch (err) {
+              persistLog.error("seed:instance-error", {
+                entity: entity.name,
+                id: instance.id,
+                error: err instanceof Error ? err : String(err)
+              });
+              return null;
+            }
+          })
+        );
+        const successCount = results.filter((r) => r !== null).length;
+        persistLog.debug("seed:done", { entity: entity.name, success: successCount, total: instances.length });
+      }
+    } else if (this.config.mode === "mock" && this.persistence instanceof MockPersistenceAdapter) {
+      if (this.config.debug) {
+        persistLog.debug("mock:generate", { entity: entity?.name });
+      }
+      if (entity?.name && entity.fields) {
+        const fields = entity.fields.filter(
+          (f) => typeof f.name === "string" && f.name.length > 0
+        );
+        this.persistence.registerEntity({ name: entity.name, fields });
+        if (this.config.debug) {
+          persistLog.debug("mock:seeded", { entity: entity.name, count: this.persistence.count(entity.name) });
+        }
+      }
+    }
+    const auxiliaryEntities = orbital.auxiliaryEntities;
+    if (auxiliaryEntities !== void 0 && auxiliaryEntities.length > 0 && this.config.mode === "mock" && this.persistence instanceof MockPersistenceAdapter) {
+      for (const auxRef of auxiliaryEntities) {
+        if (typeof auxRef === "string" || isEntityCall(auxRef)) continue;
+        const auxEntity = auxRef;
+        if (!auxEntity.name || !auxEntity.fields) continue;
+        const auxFields = auxEntity.fields.filter(
+          (f) => typeof f.name === "string" && f.name.length > 0
+        );
+        this.persistence.registerEntity({ name: auxEntity.name, fields: auxFields });
+        if (this.config.debug) {
+          persistLog.debug("mock:seeded-auxiliary", {
+            entity: auxEntity.name,
+            count: this.persistence.count(auxEntity.name)
+          });
+        }
+      }
+    }
+    if (this.config.debug) {
+      registerLog.debug("register:orbital", {
+        name: orbital.name,
+        traitCount: (orbital.traits || []).length
+      });
+    }
+  }
+  /**
+   * Register a single orbital (sync wrapper for backward compatibility)
+   */
+  registerOrbital(orbital) {
+    this.registerOrbitalAsync(orbital).catch((err) => {
+      registerLog.error("register:failed", {
+        name: orbital.name,
+        error: err instanceof Error ? err : String(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) {
+              xOrbitalLog.debug("listen:received", () => ({
+                receiverOrbital: orbitalName,
+                receiverTrait: trait.name,
+                event: listener.event,
+                sourceOrbital: event.source?.orbital ?? "?",
+                sourceTrait: 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) {
+      registerLog.debug("register:ticks", { count: this.tickBindings.length });
+    }
+  }
+  /**
+   * 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) {
+      registerLog.debug("register:tick", {
+        orbital: orbitalName,
+        trait: traitName,
+        tick: tick.name,
+        intervalMs
+      });
+    }
+    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) {
+      registerLog.warn("register:tick-invalid-interval", { interval, defaultMs: 1e3 });
+      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) {
+        effectLog.debug("tick:processing", () => ({
+          orbital: orbitalName,
+          trait: traitName,
+          tick: tick.name,
+          entityCount: entities.length
+        }));
+      }
+      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) {
+                effectLog.debug("tick:guard-failed", () => ({
+                  tick: tick.name,
+                  entityId: typeof entity.id === "string" ? entity.id : void 0
+                }));
+              }
+              continue;
+            }
+          } catch (error) {
+            effectLog.error("tick:guard-error", {
+              tick: tick.name,
+              entityId: typeof entity.id === "string" ? entity.id : void 0,
+              error: error instanceof Error ? error : String(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) {
+            effectLog.debug("tick:effects-executed", () => ({
+              tick: tick.name,
+              entityId: typeof entity.id === "string" ? entity.id : void 0
+            }));
+          }
+        }
+      }
+    } catch (error) {
+      effectLog.error("tick:execute-error", {
+        tick: tick.name,
+        error: error instanceof Error ? error : String(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
+        );
+        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;
+      }
+    }
+    const entityByTrait = {};
+    for (const [name, fields] of registered.traitFieldStates) {
+      if (fields && Object.keys(fields).length > 0) {
+        entityByTrait[name] = fields;
+      }
+    }
+    const results = registered.manager.sendEvent(
+      event,
+      cleanPayload,
+      entityData,
+      entityByTrait
+    );
+    const filteredResults = activeTraits && activeTraits.length > 0 ? results.filter(({ traitName }) => activeTraits.includes(traitName)) : results;
+    if (this.config.debug && activeTraits) {
+      busLog.debug("dispatch:filter-traits", () => ({
+        total: results.length,
+        active: filteredResults.length,
+        activeTraits: 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) {
+          busLog.debug("emit:dispatch", () => ({
+            event,
+            payloadJson: JSON.stringify(eventPayload ?? null),
+            sourceOrbital: source?.orbital,
+            sourceTrait: source?.trait
+          }));
+        }
+        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) => {
+        let fieldState = registered.traitFieldStates.get(traitName);
+        if (!fieldState) {
+          fieldState = {};
+          registered.traitFieldStates.set(traitName, fieldState);
+        }
+        fieldState[field] = value;
+        effectResults.push({
+          effect: "set",
+          entityType,
+          data: { id: targetId || entityId || "", field, value },
+          success: true
+        });
+      },
+      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 if (this.config.mode === "mock") {
+            const mockId = `mock_${service}_${action}_${Math.random().toString(36).slice(2, 10)}`;
+            const paramsEcho = {};
+            if (params) {
+              for (const [k, v] of Object.entries(params)) {
+                if (v !== void 0 && (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v === null || v instanceof Date)) {
+                  paramsEcho[k] = v;
+                }
+              }
+            }
+            result = {
+              id: mockId,
+              clientSecret: `secret_${mockId}`,
+              success: true,
+              status: "succeeded",
+              ...paramsEcho
+            };
+          } else {
+            effectLog.warn("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 {
+          xOrbitalLog.info("fetch:enter", () => ({
+            entityType: fetchEntityType,
+            hasOptions: options !== void 0 && options !== null,
+            optionsKeys: options ? Object.keys(options).join(",") : "",
+            filterType: typeof options?.filter,
+            filterIsArray: Array.isArray(options?.filter),
+            filterJson: JSON.stringify(options?.filter ?? null).slice(0, 300),
+            payloadJson: JSON.stringify(bindingsRef?.payload ?? null).slice(0, 300)
+          }));
+          let result = null;
+          let total = 0;
+          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;
+              total = 1;
+            }
+          } else {
+            let entities = await this.persistence.list(fetchEntityType);
+            if (options?.filter !== void 0 && options.filter !== null) {
+              const predicate = options.filter;
+              entities = entities.filter((entity) => {
+                const ctx = createContextFromBindings(
+                  { entity, payload: bindingsRef?.payload, current: entity },
+                  false
+                );
+                try {
+                  return Boolean(evaluate(predicate, ctx));
+                } catch (err) {
+                  effectLog.error("fetch:filter-eval-error", {
+                    entityType: fetchEntityType,
+                    error: err instanceof Error ? err : String(err)
+                  });
+                  return false;
+                }
+              });
+            }
+            total = entities.length;
+            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;
+          }
+          return result === null ? null : { rows: result, total };
+        } catch (error) {
+          effectLog.error("fetch:error", {
+            entityType: fetchEntityType,
+            error: error instanceof Error ? error : String(error)
+          });
+          return null;
+        }
+      },
+      // Resource operators: ref, deref, swap, watch, atomic
+      ref: async (refEntityType, options) => {
+        try {
+          return await handlers.fetch(refEntityType, options);
+        } catch (error) {
+          effectLog.error("ref:error", {
+            entityType: refEntityType,
+            error: error instanceof Error ? error : String(error)
+          });
+          return null;
+        }
+      },
+      deref: async (derefEntityType, options) => {
+        try {
+          let result = null;
+          let total = 0;
+          if (options?.id) {
+            const entity = await this.persistence.getById(derefEntityType, options.id);
+            if (entity) {
+              fetchedData[derefEntityType] = [entity];
+              result = entity;
+              total = 1;
+            }
+          } else {
+            const entities = await this.persistence.list(derefEntityType);
+            fetchedData[derefEntityType] = entities;
+            result = entities;
+            total = entities.length;
+          }
+          effectResults.push({
+            effect: "deref",
+            entityType: derefEntityType,
+            success: true
+          });
+          return result === null ? null : { rows: result, total };
+        } 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) {
+          effectLog.debug("watch:noop-server", { entityType: _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) {
+          effectLog.info("notify", { type, message });
+        }
+        pushClientEffect(["notify", message, { type }]);
+      },
+      log: (message, level) => {
+        if (level === "error") {
+          dynamicLog.error(message);
+        } else if (level === "warn") {
+          dynamicLog.warn(message);
+        } else {
+          dynamicLog.debug(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 traitDef = registered.traits.find((t) => t.name === traitName);
+    const declaredDefaults = collectDeclaredConfigDefaults(traitDef);
+    const callSiteOverride = registered.configByTrait.get(traitName);
+    if (declaredDefaults || callSiteOverride) {
+      bindings.config = { ...declaredDefaults ?? {}, ...callSiteOverride ?? {} };
+    }
+    const traitFieldState = registered.traitFieldStates.get(traitName);
+    if (traitFieldState) {
+      bindings.entity = traitFieldState;
+    }
+    if (entityType) {
+      bindings[entityType] = bindings.entity ?? 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) {
+              persistLog.debug("cascade-delete", {
+                count: affectedRecords.length,
+                entityType: referringEntityType
+              });
+            }
+            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) {
+              persistLog.debug("nullify", {
+                field: field.name,
+                count: affectedRecords.length,
+                entityType: referringEntityType
+              });
+            }
+            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) {
+        persistLog.debug("populate:skip", {
+          entityType,
+          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) {
+        persistLog.warn("populate:no-entity-def", { 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) {
+          persistLog.warn("populate:no-relation-field", { includeField, 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) {
+            persistLog.error("populate:fetch-related-error", {
+              entityType: relatedEntityType,
+              error: error instanceof Error ? error : String(error)
+            });
+          }
+        }
+      }
+      const populatedFieldName = includeField.endsWith("Id") ? includeField.slice(0, -2) : includeField;
+      const isSelfRef = relatedEntityType === entityType;
+      const hydrateClone = (id) => {
+        const related = relatedEntities.get(id);
+        if (!related) return void 0;
+        const copy = { ...related };
+        if (isSelfRef) copy[foreignKeyField] = [];
+        return copy;
+      };
+      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: hydrateClone(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(hydrateClone).filter(Boolean),
+              writable: true,
+              enumerable: true,
+              configurable: true
+            });
+          } else if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
+            Object.defineProperty(entity, populatedFieldName, {
+              value: [hydrateClone(fkValue)],
+              writable: true,
+              enumerable: true,
+              configurable: true
+            });
+          }
+        }
+      }
+      if (this.config.debug) {
+        persistLog.debug("populate:done", {
+          field: populatedFieldName,
+          count: entities.length,
+          entityType
+        });
+      }
+    }
+  }
+  // ==========================================================================
+  // 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