@almadar/shell-node 0.1.0 → 1.1.0

package/dist/chunk-34JOE763.js

@@ -0,0 +1,845 @@
+import { installNodeHostPorts, createNodeTokenPost } from './chunk-VQVAHUAX.js';
+import { nativeMemoryOf } from './chunk-EEYGL7AB.js';
+import { EventBus, bindDeclaredCollections, createSecretPorts, defaultCallService, kernelEventRequestParser, kernelOsTls, kernelOsCompletions, stampEmitSource, eventRouteKey, kernelOsGrants, KernelEngine, dispatchDeclaredInput, dispatchInbound, createSecretStore, evaluateOnKernel, InFlightCalls } from '@almadar/shell-runtime';
+import { installKernelEvaluator, orbitalInlineEntities, asEventId, asTraitId, inlineTraitRefs, tickEventKey, toPayloadValue } from '@almadar/core';
+import { createLogger } from '@almadar/logger';
+
+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");
+createLogger("almadar:runtime:persist");
+var registerLog = createLogger("almadar:runtime:register");
+var TICK_PASS_MS = 16;
+function isNodeEnv() {
+  return typeof process !== "undefined" && Boolean(process.versions?.node);
+}
+var UnresolvedProgramError = class extends Error {
+  constructor(schemaName) {
+    super(`program "${schemaName}" has unresolved imports and this host cannot run orb: register its resolved form (orb resolve)`);
+    this.name = "UnresolvedProgramError";
+  }
+};
+function needsResolving(schema) {
+  for (const orbital of schema.orbitals) {
+    for (const t of orbital.traits ?? []) {
+      if (typeof t === "object" && "ref" in t && t.ref.includes(".") && t._resolved === void 0) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+var OrbitalServerRuntime = class {
+  orbitals = /* @__PURE__ */ new Map();
+  eventBus;
+  config;
+  /** The row store a host-supplied `persistence` replaces: the kernel's own `MemoryStore`, opened by the first `register()`. */
+  ownedStore;
+  /**
+   * The bound persistence adapter (host-supplied, else the kernel's own memory store). Public so a test can
+   * inspect committed rows honestly. A runtime that owns its store has one from the first `register()`.
+   */
+  get persistence() {
+    const store = this.config.persistence ?? this.ownedStore;
+    if (store === void 0) throw new Error("OrbitalServerRuntime: the runtime opens its store when a program is registered; none is registered yet");
+    return store;
+  }
+  /** The kernel running the registered program; null before a program is registered. */
+  kernelEngine = null;
+  /** What the kernel holds of every trait of the registered program, read once when the kernel opens. */
+  programSurface;
+  /** The `os` handles of the program the kernel runs; closed when that program is replaced, reset or dropped. */
+  kernelOs;
+  /** Drives the kernel's one tick clock: every pass asks `KernelEngine.tickPass` which ticks are due. */
+  tickTimer = null;
+  programHandlersPromise = null;
+  resolvedSchema = null;
+  /** The folder the program's lazy files sit beside; the pages that name them are on `resolvedSchema.lazyPages`. */
+  lazyDir;
+  /** Wired by the hosting server (e.g. the playground SSE endpoint) via `setLiveBroadcastSink`. */
+  liveSubscribers = /* @__PURE__ */ new Set();
+  liveBroadcastSink = null;
+  hostDispatchSink = null;
+  /** The one-shot timer that flushes the kernel's coalesced tick relay window. */
+  tickRelayTimer = null;
+  constructor(config) {
+    installNodeHostPorts();
+    this.config = { ...config };
+    this.eventBus = new EventBus();
+  }
+  /**
+   * Lazily wire the program host handlers (behavior/* and program/* effects),
+   * merging them UNDER any user-provided handlers. Only when `programHost`
+   * is configured; otherwise the effects fail explicitly.
+   */
+  async ensureProgramHandlers() {
+    if (!isNodeEnv()) return;
+    const host = this.config.programHost;
+    if (host === void 0) return;
+    if (!this.programHandlersPromise) {
+      this.programHandlersPromise = (async () => {
+        const { createProgramHandlers } = await import('./createProgramHandlers.js');
+        this.config.effectHandlers = {
+          ...createProgramHandlers(host),
+          ...this.config.effectHandlers
+        };
+      })();
+    }
+    return this.programHandlersPromise;
+  }
+  // ==========================================================================
+  // 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.
+   */
+  /**
+   * The in-flight (or last-completed) app mutation — `register()` chains its
+   * body onto this, and `unregisterAll()` stamps a marker after clearing.
+   * `processOrbitalEvent` consults it when the requested orbital is missing:
+   * during a catalog-style app swap the new schema's registration is already
+   * in flight while a client's first events arrive, and answering those with
+   * an immediate `Orbital not found` 404 (the pre-fix behavior) races the
+   * swap — big multi-orbital organisms lost their mount INITs intermittently
+   * while single-orbital ones almost always won. Awaiting the epoch and
+   * re-reading the map turns the race into a brief wait. `BrowserPlayground`
+   * gated dispatches on registration ad hoc for the same race; the epoch is
+   * the canonical, host-wide fix.
+   */
+  registrationEpoch = null;
+  /**
+   * Reentrancy guard for `withRegistrationMutation`. While a bracket is
+   * open, `register()`/`unregisterAll()` must NOT chain/stamp the epoch:
+   * the callback's sequential awaits already order them, and chaining a
+   * `register()` awaited by the callback onto the bracket's gate would
+   * deadlock (callback → register → epoch → gate → callback's finally).
+   */
+  registrationMutationDepth = 0;
+  async register(schema, options = {}) {
+    if (this.registrationMutationDepth > 0) {
+      await this.doRegister(schema, options);
+      return;
+    }
+    const previous = this.registrationEpoch ?? Promise.resolve();
+    const epoch = previous.then(
+      () => this.doRegister(schema, options),
+      () => this.doRegister(schema, options)
+    );
+    this.registrationEpoch = epoch;
+    await epoch;
+  }
+  async doRegister(schema, options) {
+    const kernel = await this.kernelModule();
+    installKernelEvaluator(kernel);
+    this.openOwnedStore(kernel);
+    if (this.config.debug) {
+      registerLog.debug("register:schema", { name: schema.name });
+    }
+    if (needsResolving(schema)) schema = await this.resolveWithOrb(schema);
+    this.lazyDir = options.lazyDir;
+    if ((schema.lazyPages ?? []).length > 0 && this.lazyDir === void 0) {
+      throw new Error(`OrbitalServerRuntime: program "${schema.name}" lists lazy pages and no folder their files sit beside was given; register it from its file`);
+    }
+    for (const orbital of schema.orbitals) {
+      await this.registerOrbitalAsync(orbital);
+    }
+    await this.openKernel(schema);
+    this.resolvedSchema = schema;
+  }
+  /** The kernel's own row store, opened once in the register phase when the host supplied none. */
+  openOwnedStore(kernel) {
+    if (this.config.persistence !== void 0 || this.ownedStore !== void 0) return;
+    this.ownedStore = nativeMemoryOf(kernel);
+  }
+  /**
+   * 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}`);
+    }
+    const { dirname } = await import('path');
+    await this.register(schema, { lazyDir: dirname(path) });
+  }
+  /** A program with imports resolved by `orb` from the configured base path (Node only: the one resolver is the compiler). */
+  async resolveWithOrb(schema) {
+    if (!isNodeEnv()) throw new UnresolvedProgramError(schema.name);
+    const { programResolveSchema } = await import('./program-6DB6LK5B.js');
+    const cwd = this.programRoot();
+    if (this.config.debug) registerLog.debug("register:resolve-with-orb", { name: schema.name, cwd });
+    return programResolveSchema(schema, { cwd, ...this.config.programHost?.orbBin !== void 0 ? { orbBin: this.config.programHost.orbBin } : {} });
+  }
+  /**
+   * Register a single orbital
+   */
+  async registerOrbitalAsync(orbital) {
+    this.orbitals.set(orbital.name, { schema: orbital });
+    bindDeclaredCollections(this.persistence, orbitalInlineEntities(orbital));
+    if (this.config.debug) {
+      registerLog.debug("register:orbital", {
+        name: orbital.name,
+        traitCount: (orbital.traits || []).length
+      });
+    }
+  }
+  /** The adapters the kernel's I/O is answered with: this runtime's persistence, services and program host. */
+  secretPorts() {
+    const options = this.config.secretPorts;
+    if (options === void 0) return void 0;
+    const kernel = this.config.kernel;
+    if (kernel === void 0 || options.tokenPost !== void 0) return createSecretPorts(options);
+    const tokenPost = createNodeTokenPost({ egressAllows: (url) => this.requireKernelEngine().egressAllows(url), isPublicAddress: (ip) => kernel.isPublicAddress(ip) });
+    return createSecretPorts({ tokenPost, ...options });
+  }
+  kernelPorts() {
+    const secretPorts = this.secretPorts();
+    return {
+      ...secretPorts !== void 0 ? { secretPorts } : {},
+      ...this.config.clock !== void 0 ? { now: this.config.clock } : {},
+      ...this.kernelOs !== void 0 ? { os: this.kernelOs } : {},
+      ...this.kernelOs !== void 0 && this.config.kernel !== void 0 ? { osCompletions: kernelOsCompletions(this.config.kernel) } : {},
+      ...this.kernelOs !== void 0 ? { osTls: kernelOsTls(() => this.requireKernelEngine()) } : {},
+      ...this.config.kernel !== void 0 ? { parseEventRequest: kernelEventRequestParser(this.config.kernel) } : {},
+      persistence: this.persistence,
+      inFlightCalls: this.inFlightCalls,
+      callService: (service, action, params, context) => {
+        const provider = this.config.effectHandlers?.callService;
+        if (provider !== void 0) return provider(service, action, params, context);
+        return defaultCallService(service, action, params, context);
+      },
+      programEffect: () => this.config.effectHandlers?.programEffect,
+      substrateStream: (op, args) => {
+        if (op !== "program/live") return void 0;
+        const first = args[0];
+        const options = first !== null && typeof first === "object" && !Array.isArray(first) ? first : {};
+        const clientId = typeof options["clientId"] === "string" ? options["clientId"] : void 0;
+        return {
+          subscribe: (message) => {
+            const engine = this.requireKernelEngine();
+            const stream = clientId !== void 0 ? engine.openSessionStream(clientId) : void 0;
+            const receive = (item) => {
+              if (engine.liveItemDelivered(item, clientId)) message(toPayloadValue({ event: item.event, ...item.payload !== void 0 ? { payload: item.payload } : {}, source: item.source }));
+            };
+            this.liveSubscribers.add(receive);
+            return () => {
+              this.liveSubscribers.delete(receive);
+              if (stream !== void 0) engine.closeSessionStream(stream);
+            };
+          }
+        };
+      },
+      servicePorts: (caller, user, message, assertReentry) => this.servicePorts(caller, user, message, assertReentry),
+      deliverLive: (site, payload, originClientId) => this.deliverLiveMessage(site, payload, originClientId),
+      deferCallOutcome: () => this.hostDispatchSink === null ? void 0 : (call) => this.runDeferredOutcome(call.orbital, {
+        event: call.event,
+        ...call.payload !== void 0 ? { payload: call.payload } : {},
+        ...call.heldPayload !== void 0 ? { heldPayload: call.heldPayload } : {},
+        targetTrait: call.traitName,
+        ...call.entityId !== void 0 ? { entityId: call.entityId } : {},
+        ...call.originClientId !== void 0 ? { clientId: call.originClientId } : {},
+        ...call.locale !== void 0 ? { locale: call.locale } : {}
+      })
+    };
+  }
+  /** One live message of a running `call-service`, stamped as its calling trait, to the requesting tab only. */
+  deliverLiveMessage(site, payload, originClientId) {
+    const registered = this.orbitals.get(site.orbital);
+    const callingTrait = this.traitsOf(site.orbital).find((t) => t.name === site.trait);
+    const stamp = stampEmitSource(void 0, {
+      orbitalName: site.orbital,
+      traitName: site.trait,
+      orbitalId: registered?.schema.id,
+      traitId: callingTrait?.traitId === void 0 ? void 0 : asTraitId(callingTrait.traitId),
+      emitContractEventId: ((eventId) => eventId === void 0 ? void 0 : asEventId(eventId))(callingTrait?.emits.find((e) => e.event === site.event)?.eventId),
+      originClientId
+    });
+    this.eventBus.emit(site.event, payload, stamp, eventRouteKey(site.event, stamp.eventId));
+    this.publishLiveItem({ event: site.event, payload, source: stamp, originClientId, target: "origin" });
+  }
+  /** The traits of one orbital as the kernel holds them. */
+  traitsOf(orbital) {
+    return (this.programSurface?.traits ?? []).filter((trait) => trait.orbital === orbital);
+  }
+  /** The project root this runtime hands `orb` and the kernel's language data: the program host's cwd, else the loader base path. */
+  programRoot() {
+    return this.config.programHost?.cwd ?? this.config.loaderConfig?.basePath ?? process.cwd();
+  }
+  /** The kernel module this runtime runs on: the one the host handed in, else the installed `@almadar/kernel`. */
+  async kernelModule() {
+    if (this.config.kernel !== void 0) return this.config.kernel;
+    const { loadInstalledKernel } = await import('./kernel-loader-3JR6LJV5.js');
+    this.config.kernel = await loadInstalledKernel(this.programRoot());
+    return this.config.kernel;
+  }
+  /** (Re)open the kernel on the program just registered. */
+  async openKernel(registered) {
+    const kernel = await this.kernelModule();
+    const schema = { ...registered, orbitals: inlineTraitRefs(registered.orbitals) };
+    for (const orbital of schema.orbitals) {
+      for (const trait of orbital.traits ?? []) {
+        if (typeof trait === "object" && "ref" in trait && !("stateMachine" in trait)) {
+          throw new Error(`OrbitalServerRuntime: the kernel takes an orb-resolved program, but trait "${trait.ref}" of orbital "${orbital.name}" is still a reference`);
+        }
+      }
+    }
+    this.inFlightCalls.cancelAll();
+    this.kernelEngine?.dispose();
+    this.kernelOs?.close();
+    this.kernelOs = this.config.osHost?.(kernelOsGrants(kernel, () => this.requireKernelEngine()));
+    this.kernelEngine = KernelEngine.open(kernel, schema, this.kernelPorts(), this.lazyDir);
+    this.kernelEngine.setStateful();
+    this.programSurface = this.kernelEngine.programSurface();
+    if (this.config.tickRelayIntervalMs !== void 0) this.kernelEngine.setTickRelayInterval(this.config.tickRelayIntervalMs);
+    this.restartTickClock();
+    await this.mountBootEndpoints();
+  }
+  /** Run the kernel's boot mounts for the server side (EXEC-ENDPOINT-3): the host sends what the kernel lists and chooses nothing. */
+  async mountBootEndpoints() {
+    const owners = /* @__PURE__ */ new Map();
+    for (const trait of this.programSurface?.traits ?? []) {
+      const registered = this.orbitals.get(trait.orbital);
+      if (registered !== void 0) owners.set(trait.name, registered);
+    }
+    const batches = /* @__PURE__ */ new Map();
+    for (const seed of this.requireKernelEngine().bootMounts("server")) {
+      const owner = owners.get(seed.trait);
+      if (owner === void 0) continue;
+      batches.set(owner, [...batches.get(owner) ?? [], seed]);
+    }
+    for (const [registered, mount] of batches) {
+      const first = mount[0];
+      if (first === void 0) continue;
+      const response = await this.evaluateForOrbital(registered, { event: first.event, mount, payload: {} });
+      if (!response.success) {
+        throw new Error(`OrbitalServerRuntime: the boot mount of orbital "${registered.schema.name}" failed: ${response.error ?? "the kernel refused it"}`);
+      }
+    }
+  }
+  /** What answers the declared contract: the registered program's kernel, else the kernel's own program-less answers, which refuse every input and hook. */
+  async contractEngine() {
+    return this.kernelEngine ?? KernelEngine.withoutProgram(await this.kernelModule());
+  }
+  requireKernelEngine() {
+    if (this.kernelEngine === null) throw new Error("OrbitalServerRuntime: an os ask arrived with no kernel program registered");
+    return this.kernelEngine;
+  }
+  /** Ask the kernel's clock which ticks are due and start each as a `runTick` request to the orbital it names. */
+  tickPass() {
+    const engine = this.kernelEngine;
+    if (engine === null) return;
+    for (const [orbital, ticks] of Object.entries(engine.tickPass(performance.now()))) {
+      for (const due of ticks) void this.executeTick(orbital, due.trait, due.tick);
+    }
+  }
+  /** Run the kernel's clock on this host's timer when the program declares a tick. */
+  restartTickClock() {
+    this.cleanupTicks();
+    if (this.kernelEngine?.declaresTicks() !== true) return;
+    this.tickTimer = setInterval(() => this.tickPass(), TICK_PASS_MS);
+  }
+  /** A tick: the host owns the timer, the kernel decides whether and over which rows it fires. */
+  async executeTick(orbitalName, traitName, tickName) {
+    const response = await this.processOrbitalEvent(orbitalName, {
+      event: tickEventKey(tickName),
+      runTick: { trait: traitName, tick: tickName },
+      targetTrait: traitName
+    });
+    if (!response.success) {
+      effectLog.error("tick:execute-error", { tick: tickName, error: response.error ?? "the kernel refused the tick" });
+    }
+  }
+  /**
+   * Stop the host's timers
+   */
+  cleanupTicks() {
+    if (this.tickTimer !== null) clearInterval(this.tickTimer);
+    this.tickTimer = null;
+    if (this.tickRelayTimer !== null) clearTimeout(this.tickRelayTimer);
+    this.tickRelayTimer = null;
+  }
+  /**
+   * Unregister all orbitals and clean up
+   */
+  unregisterAll() {
+    this.cleanupTicks();
+    this.orbitals.clear();
+    this.inFlightCalls.cancelAll();
+    this.kernelEngine?.dispose();
+    this.kernelEngine = null;
+    this.programSurface = void 0;
+    this.kernelOs?.close();
+    this.kernelOs = void 0;
+    this.eventBus.clear();
+    this.programHandlersPromise = null;
+    if (this.registrationMutationDepth === 0) {
+      this.registrationEpoch = (this.registrationEpoch ?? Promise.resolve()).then(() => void 0, () => void 0);
+    }
+  }
+  /**
+   * Bracket a multi-step app mutation (the classic swap is
+   * `unregisterAll()` → resolve next schema → `register()`) as ONE
+   * registration epoch. `register()` alone chains only its own body onto
+   * the epoch, so between `unregisterAll()` and the `register()` call the
+   * runtime's map is empty while the epoch marker has already resolved —
+   * any `processOrbitalEvent` that lands in that gap (the resolve of a big
+   * organism takes real time) 404s `Orbital not found` even though the
+   * requested orbital is milliseconds away from landing. Inside this
+   * bracket the epoch stays pending for the WHOLE callback, so mid-swap
+   * dispatches await the completed swap and then resolve against the new
+   * app. A failed callback still releases the epoch (chained on both
+   * branches), so a failed swap falls through to the honest 404 instead of
+   * wedging the queue. Callbacks SERIALIZE: each bracket awaits the previous
+   * epoch before running `fn`, so two hosts swapping at once (a catalog
+   * select racing a preview remount's `/register`) cannot interleave their
+   * unregister/register sequences into a mixed registry. A bracket opened
+   * from INSIDE another bracket's callback runs `fn` directly — detected
+   * via the AsyncLocalStorage context below (a depth counter alone can't
+   * tell a true nest from a concurrent caller) — because the outer
+   * callback's awaits already serialize it and queueing on the outer gate
+   * would deadlock. Deadlock-free otherwise: `doRegister` never dispatches
+   * events, so awaiting dispatches never block registration progress.
+   */
+  /**
+   * Reentrancy context for `withRegistrationMutation`. A depth counter alone
+   * cannot distinguish "called from inside a bracket callback" (must run
+   * directly — queueing on the outer gate would deadlock) from "called
+   * concurrently while another bracket is in flight" (must queue — running
+   * directly would interleave two swaps). The ALS marks the callback's async
+   * context, which separates the two exactly.
+   */
+  bracketAls = null;
+  ensureBracketAls() {
+    this.bracketAls ??= import('async_hooks').then(
+      ({ AsyncLocalStorage }) => new AsyncLocalStorage()
+    );
+    return this.bracketAls;
+  }
+  async withRegistrationMutation(fn) {
+    const previous = this.registrationEpoch ?? Promise.resolve();
+    let release = () => void 0;
+    const gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    this.registrationEpoch = previous.then(() => gate, () => gate);
+    this.registrationMutationDepth++;
+    try {
+      const als = await this.ensureBracketAls();
+      if (als.getStore() !== void 0) {
+        release();
+        return await fn();
+      }
+      await previous.catch(() => void 0);
+      const nestingToken = /* @__PURE__ */ Symbol("withRegistrationMutation");
+      return await als.run(nestingToken, fn);
+    } finally {
+      this.registrationMutationDepth--;
+      release();
+    }
+  }
+  /**
+   * Return every registered orbital's circuit to boot: trait states to their
+   * initial states, frames and row cache emptied, and a fresh mount (no trait
+   * awaiting INIT, nothing held).
+   */
+  resetCircuitState() {
+    this.inFlightCalls.cancelAll();
+    this.kernelEngine?.reset();
+    this.kernelOs?.close();
+  }
+  /**
+   * Wire a live-broadcast sink. Called only from a `persist` effect's
+   * `emit:{success}` envelope firing site (batch and single-op) — see
+   * `docs/Almadar_Live_Push.md`. The hosting server (e.g. the playground's
+   * `/api/events` SSE endpoint) uses this to fan persist mutations out to
+   * every OTHER connected client; a fresh call replaces the previous sink.
+   */
+  setLiveBroadcastSink(sink) {
+    this.liveBroadcastSink = sink;
+  }
+  publishLiveItem(item) {
+    this.liveBroadcastSink?.(item);
+    for (const receive of this.liveSubscribers) receive(item);
+  }
+  /** Wire where a host-run dispatch's result goes (see `HostDispatchItem`); a fresh call replaces the previous sink. */
+  setHostDispatchSink(sink) {
+    this.hostDispatchSink = sink;
+  }
+  /** Run a follow-on step's call outcome as its own dispatch, and hand its result to the host-dispatch sink. */
+  runDeferredOutcome(orbitalName, request) {
+    void this.processOrbitalEvent(orbitalName, request).then(
+      (response) => this.hostDispatchSink?.({ orbitalName, request, response, ...request.clientId !== void 0 ? { originClientId: request.clientId } : {} }),
+      (error) => effectLog.error("deferred-outcome:failed", { orbitalName, event: request.event, trait: request.targetTrait, error: error.message })
+    );
+  }
+  /**
+   * A tick-stamped dispatch is a latest-state broadcast (T6): the kernel coalesces it with the others of the window
+   * (newest per origin client, orbital and event) and says how long the window stays open; this host only runs
+   * the timer.
+   */
+  queueTickRelay(orbitalName, request) {
+    const engine = this.requireKernelEngine();
+    const window = engine.relayTick(orbitalName, request);
+    if (window === void 0) return;
+    const timer = setTimeout(() => this.flushTickRelay(), window);
+    if (typeof timer === "object" && typeof timer.unref === "function") timer.unref();
+    this.tickRelayTimer = timer;
+  }
+  flushTickRelay() {
+    this.tickRelayTimer = null;
+    const engine = this.kernelEngine;
+    if (engine === null) return;
+    for (const item of engine.flushTickRelay()) this.publishLiveItem({ ...item, target: "peers" });
+  }
+  /**
+   * `reference` resolved for the identity bound to `clientId`'s session (none: the anonymous viewer) against the store as it is now: the rows that still match its query and that identity's `@read`, in the reference's order, `total` re-counted. The kernel resolves through its server
+   * resolve flight. A client reaches it with
+   * `POST /:orbital/../resolve-rows`.
+   */
+  async resolveRows(reference, clientId) {
+    const engine = this.kernelEngine;
+    const owner = engine === null ? void 0 : engine.entityOwnerOrbital(reference.entityType);
+    if (engine === null || owner === void 0) throw new Error(`${reference.entityType}: no registered orbital declares this entity`);
+    return engine.resolveRows(reference, { orbital: owner, ...clientId !== void 0 ? { originClientId: clientId } : {} });
+  }
+  // ==========================================================================
+  // Event Processing
+  // ==========================================================================
+  /**
+   * Process an event for an orbital — the stateful host's thin shell over
+   * the unified `evaluateOrbitalEvent` composition (design:
+   * docs/Almadar_Runtime_Stateless_Stateful_PLAN.md §4.1). This method owns
+   * ONLY session concerns: orbital lookup, viewer normalization, the lazy
+   * OS/substrate handler wiring, the per-request relay mask
+   * (G-RUNTIME-031 — the client's mounted set as DATA, replacing the
+   * deleted blanket `originClientId` skip), the tick snapshot relay, and
+   * the cross-orbital listens relay (a listener registered under a
+   * DIFFERENT orbital than the emitter — the per-orbital composition's
+   * in-band fan-out covers the rest). Target resolution, payload
+   * validation, the cascade, the fan-out, structured rejections, and
+   * response assembly are the composition's, identical to the stateless
+   * path.
+   *
+   * Serialization: the whole evaluation runs on ONE runtime-wide async
+   * queue. The composition commits manager state directly (no per-trait
+   * actor queue), so concurrent requests against the long-lived session
+   * manager would otherwise both evaluate from the same held state and
+   * lose a transition. Coarser than the old per-(trait, entityId) actor
+   * queues — a deliberate W4 tradeoff, recorded in the plan doc.
+   *
+   * @param onPush - Optional incremental-push callback. Called immediately
+   * when an event is emitted or a client effect fires, before the promise
+   * resolves. Used by the SSE streaming path to write items to the
+   * response as they arrive rather than buffering and flushing at the end.
+   */
+  /**
+   * Read an orbital by name, awaiting an in-flight registration mutation
+   * first when the lookup misses (G-RUNTIME-038): mid-swap lookups 404ed
+   * against the emptied map even though the requested orbital was
+   * milliseconds from landing. A failed mutation falls through to the miss.
+   */
+  async resolveRegisteredOrbital(orbitalName) {
+    let registered = this.orbitals.get(orbitalName);
+    if (!registered && this.registrationEpoch !== null) {
+      await this.registrationEpoch.catch(() => void 0);
+      registered = this.orbitals.get(orbitalName);
+    }
+    if (!registered) {
+      await this.loadLazyOrbital(orbitalName);
+      registered = this.orbitals.get(orbitalName);
+    }
+    return registered;
+  }
+  /** The first request that names a `uses lazy` orbital registers it here; the kernel loads the same file on that request's dispatch (EXEC-LOAD-2). */
+  async loadLazyOrbital(orbitalName) {
+    const dir = this.lazyDir;
+    const pages = (this.resolvedSchema?.lazyPages ?? []).filter((page) => page.orbital === orbitalName);
+    const first = pages[0];
+    if (dir === void 0 || first === void 0) return;
+    const { readFile } = await import('fs/promises');
+    const { join } = await import('path');
+    const lazyPath = join(dir, first.orbRef);
+    let lazySchema;
+    try {
+      lazySchema = JSON.parse(await readFile(lazyPath, "utf-8"));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`lazy orbital "${orbitalName}": ${first.orbRef} could not be read: ${msg}`);
+    }
+    if (!lazySchema.orbitals.some((o) => o.name === orbitalName)) {
+      throw new Error(`lazy orbital "${orbitalName}" is not in ${first.orbRef}, found: ${lazySchema.orbitals.map((o) => o.name).join(", ")}`);
+    }
+    for (const orbital of lazySchema.orbitals) {
+      await this.registerOrbitalAsync(orbital);
+    }
+  }
+  /** The program's declared external inputs: what an outside client may send which trait. */
+  listExternalInputs() {
+    return this.kernelEngine?.externalInputs() ?? [];
+  }
+  /**
+   * The outside-client input channel: an API caller, an agent acting as the
+   * user, an MCP client. Only a declared external input of the target trait is
+   * dispatched — through `processOrbitalEvent`, so guards, entity policies and
+   * cascades apply exactly as for a click. Anything else is refused with
+   * `not-an-external-input`. The app's own UI keeps using `processOrbitalEvent`.
+   */
+  /**
+   * The running app lent to one `call-service` provider as the caller: the
+   * declared inputs, the input channel as `user`, and the rows `user` may read
+   * (the entity's `@read` policy, the same rule a `fetch` effect applies).
+   */
+  servicePorts(caller, user, message = () => {
+  }, assertReentry) {
+    return {
+      caller,
+      message,
+      inputs: () => this.listExternalInputs(),
+      readableEntities: () => this.kernelEngine?.readableEntities() ?? [],
+      dispatchInput: (orbital, request) => {
+        assertReentry?.();
+        return this.dispatchExternalInput(orbital, request);
+      },
+      read: async (entity) => {
+        return this.requireKernelEngine().readRows(entity, await this.persistence.list(entity), user);
+      },
+      supportsDispatchStream: true,
+      dispatchRequest: (orbital, request, input, stream) => {
+        assertReentry?.();
+        return this.dispatchEventRequest(orbital, request, input, stream);
+      },
+      deliverInbound: (name, delivery) => this.deliverInbound(name, delivery),
+      resolveRows: (reference, clientId) => this.resolveRows(reference, clientId)
+    };
+  }
+  /**
+   * A `program/dispatch` event request, as the events route (or with `input`, the inputs route) runs it: the
+   * runs as the session's identity, never a viewer the request names. An unknown orbital is `ORBITAL_NOT_FOUND`, an undeclared
+   * locale `LOCALE_NOT_DECLARED`; an inbound-only event and an undeclared input are the routes' refusals.
+   */
+  async dispatchEventRequest(orbital, parsed, input, stream = false) {
+    const request = parsed;
+    const streamItems = [];
+    const onPush = stream ? (item) => {
+      streamItems.push({ ...item, timestamp: item.timestamp ?? Date.now() });
+    } : void 0;
+    const answer = (response2) => ({
+      ok: true,
+      response: response2,
+      ...stream ? { streamItems: [...streamItems, { type: "complete", data: response2, timestamp: Date.now() }] } : {}
+    });
+    if (await this.resolveRegisteredOrbital(orbital) === void 0) {
+      return { ok: false, error: `Orbital not found: ${orbital}`, code: "ORBITAL_NOT_FOUND", status: 404 };
+    }
+    if (input) {
+      if (request.targetTrait === void 0) {
+        return { ok: false, error: "program/dispatch: an input request names its trait", code: "NO_TRAIT", status: 400 };
+      }
+      const response2 = await this.dispatchExternalInput(orbital, {
+        targetTrait: request.targetTrait,
+        event: request.event,
+        ...request.payload !== void 0 ? { payload: request.payload } : {},
+        ...request.entityId !== void 0 ? { entityId: request.entityId } : {}
+      }, onPush);
+      return answer(response2);
+    }
+    const refusal = this.refuseInboundOnly(orbital, request);
+    if (refusal !== void 0) return answer(refusal);
+    const response = await this.processOrbitalEvent(orbital, request, onPush);
+    if (response.rejections?.[0]?.code === "locale-not-declared") {
+      return { ok: false, error: response.error ?? "the locale is not declared", code: "LOCALE_NOT_DECLARED", status: 400 };
+    }
+    return answer(response);
+  }
+  async dispatchExternalInput(orbitalName, request, onPush) {
+    return dispatchDeclaredInput(await this.contractEngine(), orbitalName, request, (orbital, req) => this.processOrbitalEvent(orbital, req, onPush));
+  }
+  /**
+   * An inbound delivery (`/api/hooks/<name>`): the runtime decides whether the name is served, runs
+   * the handler through `processOrbitalEvent` and answers; the host only carries the bytes.
+   */
+  /**
+   * An event that is an inbound hook's is delivered only by `deliverInbound`: the app's own event
+   * route refuses it, as the input channel refuses an event that is no declared input.
+   */
+  refuseInboundOnly(orbitalName, request) {
+    const only = this.kernelEngine?.inboundOnly(orbitalName, request.targetTrait, request.event);
+    if (only === void 0) return void 0;
+    const { trait } = only;
+    return {
+      success: false,
+      transitioned: false,
+      states: {},
+      emittedEvents: [],
+      error: only.message,
+      rejections: [{ code: "inbound-only-event", trait, event: request.event }]
+    };
+  }
+  async deliverInbound(name, delivery, onPush) {
+    return dispatchInbound(await this.contractEngine(), name, delivery, (orbital, req) => this.processOrbitalEvent(orbital, req, onPush), (credential) => (this.secretPorts()?.secrets ?? createSecretStore()).get(credential, void 0));
+  }
+  async processOrbitalEvent(orbitalName, request, onPush) {
+    try {
+      await this.ensureProgramHandlers();
+      const registered = await this.resolveRegisteredOrbital(orbitalName);
+      if (!registered) {
+        return {
+          success: false,
+          transitioned: false,
+          states: {},
+          emittedEvents: [],
+          error: `Orbital not found: ${orbitalName}`
+        };
+      }
+      const response = await this.evaluateForOrbital(registered, request, onPush);
+      if (request.tick !== void 0 && this.liveBroadcastSink !== null) {
+        this.queueTickRelay(orbitalName, request);
+      }
+      return response;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      xOrbitalLog.error("processOrbitalEvent:error", {
+        orbital: orbitalName,
+        event: request.event,
+        entityId: request.entityId,
+        error: message
+      });
+      return {
+        success: false,
+        transitioned: false,
+        states: {},
+        emittedEvents: [],
+        error: message
+      };
+    }
+  }
+  /**
+   * One request evaluated on the kernel, which orders it among every other (EXEC-CONC-2), then its emits relayed
+   * to the host sinks.
+   */
+  async evaluateForOrbital(registered, request, onPush) {
+    const orbitalName = registered.schema.name;
+    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(this.traitsOf(orbitalName).map((trait) => ({ traitName: trait.name, currentState: this.kernelEngine?.stateOf(trait.name) ?? "" })))
+    }));
+    xOrbitalLog.debug("processOrbitalEvent:enter", () => ({
+      orbital: orbitalName,
+      event: request.event,
+      traitsInOrbital: this.traitsOf(orbitalName).map((t) => t.name).join(","),
+      payloadActiveTraits: JSON.stringify(
+        request.payload?.["_activeTraits"] ?? null
+      )
+    }));
+    const response = await evaluateOnKernel(
+      { engine: this.requireKernelEngine(), orbital: registered.schema.name, ...onPush !== void 0 ? { onStream: (item) => {
+        if (item.type === "event" || item.type === "effect") onPush(item);
+      } } : {} },
+      request,
+      request.locale
+    );
+    this.publishKernelResponse(response, void 0, request.clientId);
+    return response;
+  }
+  /**
+   * Feed the host sinks from a kernel response: the kernel answers a dispatch whole, so each emit reaches the
+   * event bus (the public firehose) and `onPush` once the dispatch is done, in the order the response carries them.
+   */
+  publishKernelResponse(response, onPush, originClientId) {
+    for (const emitted of response.emittedEvents) {
+      this.eventBus.emit(emitted.event, emitted.payload, emitted.source, eventRouteKey(emitted.event, emitted.source?.eventId));
+      if (emitted.source?.persistSuccess === true) {
+        const { persistSuccess: _mark, ...source } = emitted.source;
+        this.publishLiveItem({ event: emitted.event, ...emitted.payload !== void 0 ? { payload: emitted.payload } : {}, source, ...originClientId !== void 0 ? { originClientId } : {}, target: "peers" });
+      }
+      onPush?.({ type: "event", data: emitted });
+    }
+    for (const { effect } of response.clientEffectsByTrait ?? []) onPush?.({ type: "effect", data: effect });
+  }
+  /** This app's in-flight keyed `call-service`s, shared by every transition it runs (`cancel-call`). */
+  inFlightCalls = new InFlightCalls();
+  // ==========================================================================
+  // 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;
+    const kernel = this.kernelEngine;
+    if (kernel === null) return void 0;
+    const stateOf = (name) => {
+      const currentState = kernel.stateOf(name);
+      return currentState === "" ? void 0 : { traitName: name, currentState, previousState: null, lastEvent: null, context: {} };
+    };
+    if (traitName) return stateOf(traitName);
+    const states = {};
+    for (const trait of this.traitsOf(orbitalName)) {
+      const state = stateOf(trait.name);
+      if (state !== void 0) states[trait.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);
+  }
+};
+
+export { OrbitalServerRuntime, UnresolvedProgramError };