@almadar/runtime 6.9.3 → 6.9.5

package/dist/{OrbitalServerRuntime-CvWqVb68.d.ts → OrbitalServerRuntime-CpKcmAUY.d.ts}

@@ -1,7 +1,6 @@
-import * as _almadar_core from '@almadar/core';
-import { EventPayload, EntityRow, OrbitalSchema, Orbital, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, Entity, TraitConfig, TraitTick } from '@almadar/core';
 import { Router } from 'express';
 import { I as IEventBus, g as RuntimeEvent, f as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, i as TransitionObserver, C as ConfigContext, h as TraitState, j as TransitionResult, E as EvaluationContextExtensions, a as EffectHandlers } from './types-cuy5gd29.js';
+import { EventPayload, EntityRow, DeclaredTraitConfig, TraitConfig, OrbitalSchema, Orbital, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, OrbitalDefinition, Entity, TraitTick } from '@almadar/core';
 import { P as PersistenceAdapter } from './PersistenceAdapter-B6dQCbbU.js';
 
 /**
@@ -310,6 +309,23 @@ declare class StateMachineManager {
     resetAll(): void;
 }
 
+/**
+ * Pure config-default extraction — kept OUT of `OrbitalServerRuntime.ts` so the
+ * package index can re-export it without dragging that module's node-only
+ * imports (`module`/`createRequire`, the external loader) into a browser bundle.
+ * This file has zero node dependencies (types only, from `@almadar/core`).
+ */
+
+/**
+ * Walk a trait's declared `config { }` schema and return the flat
+ * `{ key: default, ... }` map. Seeds `@config.X` binding context with the
+ * atom's own declared defaults before any call-site override is applied.
+ * Mirrors the compiled path's `DEFAULT_<TRAIT>_CONFIG` constant (backend.rs).
+ */
+declare function collectDeclaredConfigDefaults(trait: {
+    config?: DeclaredTraitConfig;
+} | undefined): TraitConfig | undefined;
+
 /**
  * External Orbital Loader
  *
@@ -674,6 +690,41 @@ declare function parseNamespacedEvent(eventName: string): {
     event: string;
 };
 
+/**
+ * OrbitalServerRuntime - Dynamic Server-Side Orbital Execution
+ *
+ * This runtime takes an OrbitalSchema and dynamically:
+ * 1. Registers all orbitals and their traits
+ * 2. Creates Express routes for trait communication
+ * 3. Executes state machines server-side
+ * 4. Handles cross-orbital event propagation
+ *
+ * This is the "interpreted" mode - no compilation needed.
+ * The compiler generates equivalent static code for production.
+ *
+ * @example
+ * ```typescript
+ * import { OrbitalServerRuntime } from '@kflow-builder/shared/runtime';
+ * import express from 'express';
+ *
+ * const app = express();
+ * const runtime = new OrbitalServerRuntime();
+ *
+ * // Register schema (can be loaded from file, API, etc.)
+ * runtime.register(orbitalSchema);
+ *
+ * // Mount orbital routes
+ * app.use('/api/orbitals', runtime.router());
+ *
+ * // Client can now:
+ * // POST /api/orbitals/:orbital/events  - Send event to orbital
+ * // GET  /api/orbitals/:orbital/state   - Get current state
+ * // GET  /api/orbitals                  - List registered orbitals
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Client-side effect tuple shipped in `OrbitalEventResponse.clientEffects`.
  * Restricted to the three effect kinds the client knows how to apply to the
@@ -878,49 +929,6 @@ interface OrbitalServerRuntimeConfig {
     contextExtensions?: EvaluationContextExtensions;
 }
 
-/**
- * Check whether a schema needs preprocessing (has `uses` declarations or
- * un-inlined cross-orbital trait references).
- *
- * Cross-orbital refs are trait entries like
- * `{ ref: "Modal.traits.ModalRecordModal", ... }` with no inline
- * `stateMachine`. If these aren't resolved before `register()` runs, the
- * trait binder produces an empty state machine and all interactions
- * targeting the trait are silently dropped.
- */
-/**
- * Walk a trait's DECLARED config schema (`{ icon: { type, default }, ... }`)
- * and collect a flat `{ icon: <default>, ... }` map of just the default
- * values. Used to seed the `@config.X` binding context with the atom's
- * own declared defaults before any call-site override is applied. Mirrors
- * the compiled path's `DEFAULT_<TRAIT>_CONFIG` constant emitted by
- * backend.rs's Solution-1 plumbing.
- *
- * Returns `undefined` when the trait has no config schema or none of its
- * fields declare a default — keeps the caller's existing fast-path.
- */
-/**
- * Structural shape that both `@almadar/core`'s `Trait` and
- * `ResolvedTrait` satisfy: a `config?` map keyed by field name whose
- * values either carry a `default` (the declared-schema form loaded
- * from `.orb`) or are bare values (the runtime-resolved form).
- *
- * Widening to a structural parameter lets callers from the resolved
- * side (e.g., `@almadar/ui`'s `useTraitStateMachine`) pass their own
- * `ResolvedTrait` without an `as unknown as` cast.
- */
-/**
- * Read the `default` from each field of a trait's declared
- * `config { }` schema and return the flat `{ key: default, ... }`
- * map. Used to seed `@config.X` binding context with the atom's
- * own declared defaults before any call-site override is applied.
- *
- * Mirrors the compiled path's `DEFAULT_<TRAIT>_CONFIG` constant
- * emitted by `backend.rs` Solution-1.
- */
-declare function collectDeclaredConfigDefaults(trait: {
-    config?: _almadar_core.DeclaredTraitConfig;
-} | undefined): TraitConfig | undefined;
 declare class OrbitalServerRuntime {
     protected orbitals: Map<string, RegisteredOrbital>;
     private eventBus;
@@ -933,9 +941,19 @@ declare class OrbitalServerRuntime {
     private entitySharingMap;
     private eventNamespaceMap;
     private osHandlers;
+    private osHandlersPromise;
     private localPersistence;
     private resolvedSchema;
     constructor(config?: OrbitalServerRuntimeConfig);
+    /**
+     * Lazily wire the OS-level effect handlers (fs/net/child_process), merging
+     * them UNDER any user-provided handlers. Deferred out of the constructor
+     * because `./createOsHandlers.js` is ESM and `require()`-ing it from a
+     * `type: module` package throws ERR_REQUIRE_ESM — so it is dynamic-import()ed
+     * here on the first event. Node-only, idempotent (single shared load), and a
+     * no-op in the browser (the import never runs behind the isNodeEnv guard).
+     */
+    private ensureOsHandlers;
     /**
      * Lazily construct a default loader when the caller didn't provide one
      * but `register()` needs to preprocess. Looks for `@almadar/std` in the

package/dist/OrbitalServerRuntime.d.ts

@@ -1,5 +1,5 @@
-import '@almadar/core';
 import 'express';
-export { C as ClientEffectTuple, B as ClientNavigateTuple, D as ClientNotifyTuple, F as ClientRenderUITuple, G as EffectResult, H as LoaderConfig, O as OrbitalEventRequest, e as OrbitalEventResponse, J as OrbitalServerRuntime, f as OrbitalServerRuntimeConfig, R as RegisteredOrbital, j as RuntimeOrbital, k as RuntimeOrbitalSchema, l as RuntimeTrait, K as RuntimeTraitTick, n as collectDeclaredConfigDefaults, M as createOrbitalServerRuntime } from './OrbitalServerRuntime-CvWqVb68.js';
+export { C as ClientEffectTuple, B as ClientNavigateTuple, D as ClientNotifyTuple, F as ClientRenderUITuple, G as EffectResult, H as LoaderConfig, O as OrbitalEventRequest, e as OrbitalEventResponse, J as OrbitalServerRuntime, f as OrbitalServerRuntimeConfig, R as RegisteredOrbital, j as RuntimeOrbital, k as RuntimeOrbitalSchema, l as RuntimeTrait, K as RuntimeTraitTick, n as collectDeclaredConfigDefaults, M as createOrbitalServerRuntime } from './OrbitalServerRuntime-CpKcmAUY.js';
 import './types-cuy5gd29.js';
+import '@almadar/core';
 export { I as InMemoryPersistence, P as PersistenceAdapter } from './PersistenceAdapter-B6dQCbbU.js';