@almadar/runtime 4.0.1 → 4.2.0

package/dist/{OrbitalServerRuntime-DMe0zqCc.d.ts → OrbitalServerRuntime-CFMJku6Q.d.ts}

@@ -884,14 +884,32 @@ declare class OrbitalServerRuntime {
     private eventNamespaceMap;
     private osHandlers;
     private localPersistence;
+    private resolvedSchema;
     constructor(config?: OrbitalServerRuntimeConfig);
+    /**
+     * 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.
+     */
+    private ensureLoader;
     /**
      * Register an OrbitalSchema for execution.
      *
-     * If `autoPreprocess` is enabled in config and schema has `uses` declarations,
-     * it will be preprocessed first to resolve imports.
+     * 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.
      *
-     * For explicit preprocessing control, use `registerWithPreprocess()`.
+     * 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.
      */
     register(schema: OrbitalSchema): Promise<void>;
     /**
@@ -900,6 +918,25 @@ declare class OrbitalServerRuntime {
      * Use async register() for guaranteed instance seeding.
      */
     registerSync(schema: OrbitalSchema): void;
+    /**
+     * 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(): OrbitalSchema | null;
+    /**
+     * 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()`).
+     */
+    registerFromFile(path: string): Promise<void>;
     /**
      * Register an OrbitalSchema with preprocessing to resolve `uses` imports.
      *

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { B as EffectResult, C as LoaderConfig, D as LocalPersistenceAdapter, O as OrbitalEventRequest, e as OrbitalEventResponse, F as OrbitalServerRuntime, f as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, k as RuntimeOrbital, l as RuntimeOrbitalSchema, m as RuntimeTrait, G as RuntimeTraitTick, H as createOrbitalServerRuntime } from './OrbitalServerRuntime-DMe0zqCc.js';
+export { B as EffectResult, C as LoaderConfig, D as LocalPersistenceAdapter, O as OrbitalEventRequest, e as OrbitalEventResponse, F as OrbitalServerRuntime, f as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, k as RuntimeOrbital, l as RuntimeOrbitalSchema, m as RuntimeTrait, G as RuntimeTraitTick, H as createOrbitalServerRuntime } from './OrbitalServerRuntime-CFMJku6Q.js';
 import './types-CVSBlnzV.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,4 +1,4 @@
-import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-7WP4AE6X.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-Z72NLOSF.js';
 import './chunk-PZ5AY32C.js';
 import { Router } from 'express';
 import * as fs from 'fs';
@@ -649,6 +649,23 @@ var InMemoryPersistence = class {
     return collection ? Array.from(collection.values()) : [];
   }
 };
+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;
@@ -662,6 +679,7 @@ var OrbitalServerRuntime = class {
   eventNamespaceMap = {};
   osHandlers = null;
   localPersistence = null;
+  resolvedSchema = null;
   constructor(config = {}) {
     this.config = {
       mode: "mock",
@@ -701,26 +719,108 @@ var OrbitalServerRuntime = class {
       ...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 [{ createRequire }, path2] = await Promise.all([
+        import('module'),
+        import('path')
+      ]);
+      const require2 = createRequire(import.meta.url);
+      const stdPkgJson = require2.resolve("@almadar/std/package.json");
+      const stdLibPath = path2.dirname(stdPkgJson);
+      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.
    *
-   * If `autoPreprocess` is enabled in config and schema has `uses` declarations,
-   * it will be preprocessed first to resolve imports.
+   * 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.
    *
-   * For explicit preprocessing control, use `registerWithPreprocess()`.
+   * 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).
@@ -736,6 +836,44 @@ var OrbitalServerRuntime = class {
     }
     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(path2) {
+    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(path2, "utf-8");
+    let schema;
+    try {
+      schema = JSON.parse(raw);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`registerFromFile: ${path2} is not valid JSON: ${msg}`);
+    }
+    await this.register(schema);
   }
   /**
    * Register an OrbitalSchema with preprocessing to resolve `uses` imports.