@almadar/shell-runtime 0.0.0-stage → 0.1.0

package/dist/chunk-CQP5XAX6.js

@@ -0,0 +1,173 @@
+import { parseCron, cronMinuteKey, cronMatches } from './chunk-CROS2GEX.js';
+
+// src/runtime/time/TickScheduler.ts
+var EVERY_PASS = 0;
+var CRON_CHECK_INTERVAL_MS = 1e3;
+var TickScheduler = class {
+  ticks = /* @__PURE__ */ new Map();
+  nextId = 1;
+  running = false;
+  paused = false;
+  frameHandle = null;
+  hasRaf;
+  constructor() {
+    this.hasRaf = typeof requestAnimationFrame === "function" && typeof cancelAnimationFrame === "function";
+  }
+  /**
+   * Register a tick. `intervalMs <= 0` means "every pass" (a frame-interval
+   * tick, matching LOLO's `interval: "frame"`). Returns a handle to stop
+   * just this tick.
+   */
+  add(intervalMs, onDue) {
+    const id = this.nextId++;
+    this.ticks.set(id, {
+      kind: "interval",
+      intervalMs: intervalMs > 0 ? intervalMs : EVERY_PASS,
+      accumulatedMs: 0,
+      lastTimestamp: null,
+      onDue
+    });
+    this.ensureRunning();
+    return {
+      stop: () => {
+        this.ticks.delete(id);
+        this.maybeStop();
+      }
+    };
+  }
+  /**
+   * Register a cron-scheduled tick (`ticks { ... every "0 9 * * *" }`).
+   * Fires at most once per matching calendar minute. Throws if `expression` isn't a valid 5-field cron
+   * string; callers on a path the compiler has already validated (e.g.
+   * generated code) won't hit this, but a raw runtime value might.
+   */
+  addCron(expression, onDue) {
+    const fields = parseCron(expression);
+    const id = this.nextId++;
+    this.ticks.set(id, {
+      kind: "cron",
+      fields,
+      accumulatedMs: CRON_CHECK_INTERVAL_MS,
+      // check on the first pass, not after a full second
+      lastTimestamp: null,
+      lastFiredMinuteKey: -1,
+      onDue
+    });
+    this.ensureRunning();
+    return {
+      stop: () => {
+        this.ticks.delete(id);
+        this.maybeStop();
+      }
+    };
+  }
+  /** Stop every tick and the shared loop. */
+  stopAll() {
+    this.ticks.clear();
+    this.maybeStop();
+  }
+  /** True while the scheduler is paused (no tick callback fires and no backlog accumulates). */
+  get isPaused() {
+    return this.paused;
+  }
+  /**
+   * Halt the shared loop without dropping registered ticks. No `onDue`
+   * fires again until `resume()`. A no-op if already paused.
+   */
+  pause() {
+    if (this.paused) return;
+    this.paused = true;
+    this.stopLoop();
+  }
+  /**
+   * Restart the shared loop after `pause()`. Every registered tick's phase
+   * is reset (`lastTimestamp = null`) so the paused duration is never
+   * counted as elapsed time — the same "first pass just captures the
+   * timestamp" behavior a freshly `add()`-ed tick gets, which is what keeps
+   * resume from bursting a backlog of missed beats. A no-op if not paused.
+   */
+  resume() {
+    if (!this.paused) return;
+    this.paused = false;
+    for (const tick of this.ticks.values()) {
+      tick.lastTimestamp = null;
+    }
+    if (this.ticks.size > 0) {
+      this.ensureRunning();
+    }
+  }
+  ensureRunning() {
+    if (this.running || this.paused) return;
+    this.running = true;
+    if (this.hasRaf) {
+      const loop = (timestamp) => {
+        if (!this.running) return;
+        this.advance(timestamp);
+        this.frameHandle = requestAnimationFrame(loop);
+      };
+      this.frameHandle = requestAnimationFrame(loop);
+    } else {
+      this.frameHandle = setInterval(() => this.advance(Date.now()), 16);
+    }
+  }
+  maybeStop() {
+    if (this.ticks.size > 0 || !this.running) return;
+    this.stopLoop();
+  }
+  /** Cancel the active rAF/interval loop, if any, and clear the running flag. */
+  stopLoop() {
+    this.running = false;
+    if (this.frameHandle !== null) {
+      if (this.hasRaf) {
+        cancelAnimationFrame(this.frameHandle);
+      } else {
+        clearInterval(this.frameHandle);
+      }
+      this.frameHandle = null;
+    }
+  }
+  advance(timestamp) {
+    for (const tick of this.ticks.values()) {
+      if (tick.kind === "cron") {
+        this.advanceCron(tick, timestamp);
+        continue;
+      }
+      if (tick.intervalMs <= EVERY_PASS) {
+        tick.onDue();
+        continue;
+      }
+      if (tick.lastTimestamp === null) {
+        tick.lastTimestamp = timestamp;
+        continue;
+      }
+      tick.accumulatedMs += timestamp - tick.lastTimestamp;
+      tick.lastTimestamp = timestamp;
+      if (tick.accumulatedMs >= tick.intervalMs) {
+        tick.onDue();
+        tick.accumulatedMs = tick.accumulatedMs % tick.intervalMs;
+      }
+    }
+  }
+  /** Cron ticks check calendar-match at most once a second, deduped per matching minute. */
+  advanceCron(tick, timestamp) {
+    if (tick.lastTimestamp === null) {
+      tick.lastTimestamp = timestamp;
+      return;
+    }
+    tick.accumulatedMs += timestamp - tick.lastTimestamp;
+    tick.lastTimestamp = timestamp;
+    if (tick.accumulatedMs < CRON_CHECK_INTERVAL_MS) return;
+    tick.accumulatedMs = 0;
+    const now = /* @__PURE__ */ new Date();
+    const minuteKey = cronMinuteKey(now);
+    if (minuteKey !== tick.lastFiredMinuteKey && cronMatches(tick.fields, now)) {
+      tick.lastFiredMinuteKey = minuteKey;
+      tick.onDue();
+    }
+  }
+};
+function createTickScheduler() {
+  return new TickScheduler();
+}
+
+export { TickScheduler, createTickScheduler };

package/dist/chunk-CROS2GEX.js

@@ -0,0 +1,49 @@
+// src/runtime/time/cron.ts
+function parseCronField(field, min, max) {
+  const values = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    if (part === "*") {
+      for (let i = min; i <= max; i++) values.add(i);
+    } else if (part.includes("/")) {
+      const [range, stepStr] = part.split("/");
+      const step = parseInt(stepStr, 10);
+      const start = range === "*" ? min : parseInt(range, 10);
+      for (let i = start; i <= max; i += step) values.add(i);
+    } else if (part.includes("-")) {
+      const [lo, hi] = part.split("-").map(Number);
+      for (let i = lo; i <= hi; i++) values.add(i);
+    } else {
+      values.add(parseInt(part, 10));
+    }
+  }
+  return values;
+}
+function parseCron(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression (expected 5 fields): ${expression}`);
+  }
+  return {
+    minute: parseCronField(parts[0], 0, 59),
+    hour: parseCronField(parts[1], 0, 23),
+    day: parseCronField(parts[2], 1, 31),
+    month: parseCronField(parts[3], 1, 12),
+    weekday: parseCronField(parts[4], 0, 6)
+  };
+}
+function isValidCronExpression(expression) {
+  try {
+    parseCron(expression);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function cronMatches(fields, date) {
+  return fields.minute.has(date.getMinutes()) && fields.hour.has(date.getHours()) && fields.day.has(date.getDate()) && fields.month.has(date.getMonth() + 1) && fields.weekday.has(date.getDay());
+}
+function cronMinuteKey(date) {
+  return date.getFullYear() * 1e8 + date.getMonth() * 1e6 + date.getDate() * 1e4 + date.getHours() * 100 + date.getMinutes();
+}
+
+export { cronMatches, cronMinuteKey, isValidCronExpression, parseCron, parseCronField };

package/dist/chunk-D4XJTBLB.js

@@ -0,0 +1,217 @@
+import { declareCapabilities, answerRequest } from './chunk-NATGCIVM.js';
+import { DispatchLane } from './chunk-53IPZXDP.js';
+import { decodeResolveProgress, decodeProgress } from './chunk-RBUMDYFS.js';
+import { installKernelEvaluator, MountSeedSchema, EventStreamItemSchema, isEntityReferenceAny } from '@almadar/core';
+
+function declaredEntityTypes(schema) {
+  return schema.orbitals.flatMap((orbital) => [orbital.entity, ...orbital.auxiliaryEntities ?? []].flatMap((entity) => isEntityReferenceAny(entity) ? [] : [entity.name]));
+}
+var KernelEngine = class _KernelEngine {
+  constructor(kernel, schemaJson, ports, entityTypes = [], forkedFrom, providedHandle, preserveProgramContext = false) {
+    this.kernel = kernel;
+    this.schemaJson = schemaJson;
+    this.ports = ports;
+    this.entityTypes = entityTypes;
+    this.preserveProgramContext = preserveProgramContext;
+    installKernelEvaluator(kernel);
+    this.ports = {
+      ...ports,
+      substrateMessage: (site, key, value) => JSON.parse(kernel.osCompletionEvent(JSON.stringify({ ...site, emit: { success: site.emit.onMessage } }), key, JSON.stringify({ ok: value }))),
+      substrateCompletion: (site, key, op, args, outcome) => JSON.parse(kernel.substrateCompletionEvent(JSON.stringify(site), key, op, JSON.stringify(args), JSON.stringify(outcome)))
+    };
+    this.handle = providedHandle ?? forkedFrom?.fork() ?? this.openServer();
+    this.declare();
+  }
+  kernel;
+  schemaJson;
+  ports;
+  entityTypes;
+  preserveProgramContext;
+  handle;
+  lane = new DispatchLane();
+  tickMount = [];
+  messages = { locales: [], catalogs: {} };
+  /**
+   * A kernel on the same program, registered once, holding none of this one's session: every trait at its initial
+   * state, no rows the kernel held, its locales and mounted ticks kept. A stateless host serves each request a
+   * fork (EXEC-DIST-5), `ports` answering it.
+   */
+  fork(ports = this.ports) {
+    const forked = new _KernelEngine(this.kernel, this.schemaJson, ports, this.entityTypes, this.handle, void 0, this.preserveProgramContext);
+    forked.tickMount = this.tickMount;
+    forked.messages = this.messages;
+    return forked;
+  }
+  forkProgram(program, ports = this.ports) {
+    const schemaJson = JSON.stringify(program);
+    const entityTypes = [.../* @__PURE__ */ new Set([
+      ...this.entityTypes,
+      ...declaredEntityTypes(program)
+    ])];
+    return new _KernelEngine(this.kernel, schemaJson, ports, entityTypes, void 0, this.handle.forkProgram(schemaJson), true);
+  }
+  /** A server over the host's ports. */
+  openServer() {
+    return new this.kernel.Server(this.schemaJson);
+  }
+  declare() {
+    const handle = this.handle;
+    declareCapabilities(this.ports.persistence, (entityType, queryJson, writeJson) => handle.setCapabilities(entityType, queryJson, writeJson), this.entityTypes);
+  }
+  static open(kernel, schema, ports) {
+    return new _KernelEngine(kernel, JSON.stringify(schema), ports, declaredEntityTypes(schema));
+  }
+  /** A fresh kernel on the same program: every trait back at its initial state. */
+  reset() {
+    const contextualHandle = this.preserveProgramContext ? this.handle.fork() : void 0;
+    this.handle.free();
+    this.handle = contextualHandle ?? this.openServer();
+    this.declare();
+    this.handle.setTickMount(JSON.stringify(this.tickMount));
+    this.handle.setMessages(JSON.stringify(this.messages.locales), JSON.stringify(this.messages.catalogs));
+    if (this.managedProgram !== void 0) this.handle.setManagedProgram(this.managedProgram);
+  }
+  managedProgram;
+  /** The program whose declared credentials this kernel's credential effects manage beside its own (a console's app). */
+  setManagedProgram(program) {
+    this.managedProgram = JSON.stringify(program);
+    this.handle.setManagedProgram(this.managedProgram);
+  }
+  /** The program's declared locales and merged catalogs (a lazy page's behavior contributes its namespaced keys). */
+  setMessages(locales, catalogs) {
+    this.messages = { locales, catalogs };
+    this.handle.setMessages(JSON.stringify(locales), JSON.stringify(catalogs));
+  }
+  /** The traits some client has mounted: a tick that is not `[background]` fires only for these. */
+  setTickMount(traits) {
+    this.tickMount = traits;
+    this.handle.setTickMount(JSON.stringify(traits));
+  }
+  /** What this host mounts when it starts: the kernel's boot mounts for the side it serves (EXEC-ENDPOINT-3). */
+  bootMounts(side) {
+    return MountSeedSchema.array().parse(JSON.parse(this.handle.bootMounts(side)));
+  }
+  /** What mounts when a client opens `routePath` (EXEC-ENDPOINT-3). */
+  routeMounts(routePath) {
+    return MountSeedSchema.array().parse(JSON.parse(this.handle.routeMounts(routePath)));
+  }
+  /** Mock-seed the `[runtime]` entities the kernel holds itself, owner columns stamped with `viewerId`. */
+  seedRuntimeMock(viewerId) {
+    this.handle.seedRuntimeMock(viewerId);
+  }
+  dispose() {
+    this.handle.free();
+  }
+  liveItemDelivered(item, viewer, clientId) {
+    return this.handle.liveItemDelivered(JSON.stringify(item), JSON.stringify(viewer), clientId);
+  }
+  /** `OsGrants::allows` over the grants of the program this kernel runs. */
+  osAllows(requirementJson) {
+    return this.handle.osAllows(requirementJson);
+  }
+  /** Place the program's anchored grants and arguments under the host's anchors. */
+  setOsAnchors(anchorsJson) {
+    return this.handle.setOsAnchors(anchorsJson);
+  }
+  /** An `os/` call's arguments with its anchored parts resolved under the host's anchors. */
+  osResolveArgs(op, argsJson) {
+    return this.handle.osResolveArgs(op, argsJson);
+  }
+  /** The current state of a trait instance, `''` when it has none. */
+  stateOf(traitName, entityId) {
+    return this.handle.getState(traitName, entityId);
+  }
+  /**
+   * `reference` resolved for `scope.user` against the host-answered store (EXEC-RENDER-3): the rows that still
+   * match its query and the viewer's `@read` in the reference's order, a missing or hidden row omitted, and `total`
+   * re-counted (a `total: none` reference is not re-counted: the total is the resolved window). Each read the
+   * kernel makes is answered here, as in `evaluate`.
+   */
+  async resolveRows(reference, scope) {
+    const handle = this.handle;
+    let progress = decodeResolveProgress(handle.resolveRows(JSON.stringify(reference), JSON.stringify(scope.user ?? null)));
+    while (progress.status === "await") {
+      const { flight, requests } = progress;
+      let replies;
+      try {
+        replies = await Promise.all(
+          requests.map(async (pending) => ({ id: pending.id, answer: await answerRequest(this.ports, pending.request, scope) }))
+        );
+      } catch (error) {
+        handle.abandon(flight);
+        throw error;
+      }
+      progress = decodeResolveProgress(handle.resumeResolve(flight, JSON.stringify(replies)));
+    }
+    return { rows: progress.rows, total: progress.total };
+  }
+  /** Run `request` against `orbital`: start it, answer every request the kernel asks for, resume until done. */
+  async evaluate(orbital, request, scope) {
+    const guard = await this.lane.enter();
+    try {
+      const handle = this.handle;
+      let progress = decodeProgress(handle.start(orbital, JSON.stringify(request)));
+      while (progress.status === "await") {
+        const { flight, requests } = progress;
+        let replies;
+        guard.park(request.event);
+        try {
+          replies = await Promise.all(
+            requests.map(async (pending) => ({ id: pending.id, answer: await answerRequest(this.ports, pending.request, { ...scope, assertReentry: () => this.lane.assertCanReenter(guard.turn) }) }))
+          );
+        } catch (error) {
+          handle.abandon(flight);
+          throw error;
+        }
+        guard.resume();
+        progress = decodeProgress(handle.resume(flight, JSON.stringify(replies)));
+      }
+      if (scope.onStream !== void 0) {
+        const items = EventStreamItemSchema.array().parse(JSON.parse(handle.dispatchStream()));
+        for (const item of items) scope.onStream(item);
+      }
+      return progress.response;
+    } finally {
+      guard.release();
+    }
+  }
+};
+function kernelRequest(request, user, locale) {
+  const { _activeTraits: _dropped, _targetTrait: sidecarTarget, ...rest } = request.payload ?? {};
+  const payload = rest;
+  const target = request.targetTrait ?? (typeof sidecarTarget === "string" ? sidecarTarget : void 0);
+  const { payload: _payload, ...others } = request;
+  return {
+    ...others,
+    ...request.payload !== void 0 ? { payload } : {},
+    ...target !== void 0 ? { targetTrait: target } : {},
+    ...user !== void 0 ? { user } : {},
+    ...locale !== void 0 ? { locale } : {}
+  };
+}
+function withOriginClient(response, clientId) {
+  if (clientId === void 0) return response;
+  return {
+    ...response,
+    emittedEvents: response.emittedEvents.map((emitted) => emitted.source === void 0 ? emitted : { ...emitted, source: { ...emitted.source, originClientId: emitted.source.originClientId ?? clientId } })
+  };
+}
+async function evaluateOnKernel(kernel, request, user, locale) {
+  return withOriginClient(await kernel.engine.evaluate(kernel.orbital, kernelRequest(request, user, locale), {
+    orbital: kernel.orbital,
+    ...user !== void 0 ? { user } : {},
+    ...request.clientId !== void 0 ? { originClientId: request.clientId } : {},
+    ...locale !== void 0 ? { locale } : {},
+    ...request.entityId !== void 0 ? { entityId: request.entityId } : {},
+    ...kernel.onStream !== void 0 ? { onStream: (item) => {
+      if (item.type === "event" && item.data.source !== void 0 && request.clientId !== void 0) {
+        kernel.onStream?.({ ...item, data: { ...item.data, source: { ...item.data.source, originClientId: item.data.source.originClientId ?? request.clientId } } });
+      } else if (item.type === "complete") {
+        kernel.onStream?.({ ...item, data: withOriginClient(item.data, request.clientId) });
+      } else kernel.onStream?.(item);
+    } } : {},
+    ...kernel.outsideEventQueue !== void 0 ? { outsideEventQueue: kernel.outsideEventQueue } : {}
+  }), request.clientId);
+}
+
+export { KernelEngine, evaluateOnKernel, kernelRequest };

package/dist/chunk-D5USD2EX.js

@@ -0,0 +1,232 @@
+import { createHttpTransport } from './chunk-QELZ6TEJ.js';
+import { createLogger } from '@almadar/logger';
+
+var log = createLogger("almadar:runtime:server-bridge");
+var ServerBridge = class {
+  config;
+  state = {
+    connected: false,
+    eventsForwarded: 0,
+    eventsReceived: 0
+  };
+  unsubscribes = [];
+  pollTimer;
+  ws;
+  fetchFn;
+  /** The one HTTP request/response leg — shared with `@almadar/ui`'s transport (P5, EventTransport.ts). */
+  transport;
+  constructor(config) {
+    this.config = {
+      pollInterval: 5e3,
+      ...config
+    };
+    this.fetchFn = config.fetch || fetch.bind(globalThis);
+    this.transport = createHttpTransport({ serverUrl: config.serverUrl, fetch: this.fetchFn });
+  }
+  // ==========================================================================
+  // Connection Management
+  // ==========================================================================
+  /**
+   * Connect the bridge - start forwarding events
+   */
+  connect() {
+    if (this.state.connected) {
+      this.log("warn", "Already connected");
+      return;
+    }
+    this.log("info", "Connecting bridge...");
+    this.setupEventForwarding();
+    if (this.config.useWebSocket) {
+      this.setupWebSocket();
+    } else if (this.config.pollInterval && this.config.pollInterval > 0) {
+      this.setupPolling();
+    }
+    this.state.connected = true;
+    this.log("info", "Bridge connected");
+  }
+  /**
+   * Disconnect the bridge
+   */
+  disconnect() {
+    for (const unsub of this.unsubscribes) {
+      unsub();
+    }
+    this.unsubscribes = [];
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = void 0;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = void 0;
+    }
+    this.state.connected = false;
+    this.log("info", "Bridge disconnected");
+  }
+  /**
+   * Get current bridge state
+   */
+  getState() {
+    return { ...this.state };
+  }
+  // ==========================================================================
+  // Event Forwarding (Client -> Server)
+  // ==========================================================================
+  setupEventForwarding() {
+    const { eventBus, forwardEvents, forwardPattern } = this.config;
+    if (forwardEvents && forwardEvents.length > 0) {
+      for (const eventType of forwardEvents) {
+        const unsub = eventBus.on(eventType, (event) => {
+          this.forwardToServer(event);
+        });
+        this.unsubscribes.push(unsub);
+      }
+    } else if (forwardPattern) {
+      if (forwardPattern === "*") {
+        const unsub = eventBus.on("*", (event) => {
+          if (!event.type.startsWith("UI:") && !event.type.startsWith("BRIDGE:")) {
+            this.forwardToServer(event);
+          }
+        });
+        this.unsubscribes.push(unsub);
+      } else {
+        const prefix = forwardPattern.replace("*", "");
+        const unsub = eventBus.on("*", (event) => {
+          if (event.type.startsWith(prefix)) {
+            this.forwardToServer(event);
+          }
+        });
+        this.unsubscribes.push(unsub);
+      }
+    }
+  }
+  async forwardToServer(event) {
+    const { serverUrl, targetOrbital } = this.config;
+    try {
+      if (targetOrbital && targetOrbital !== "broadcast") {
+        await this.sendEventToOrbital(targetOrbital, event);
+      } else {
+        const orbitals = await this.fetchOrbitals();
+        for (const orbital of orbitals) {
+          await this.sendEventToOrbital(orbital.name, event);
+        }
+      }
+      this.state.eventsForwarded++;
+      this.log("debug", `Forwarded event: ${event.type}`);
+    } catch (error) {
+      this.state.lastError = String(error);
+      this.log("error", `Failed to forward event: ${event.type}`, error instanceof Error ? error : String(error));
+    }
+  }
+  async sendEventToOrbital(orbitalName, event) {
+    const request = { event: event.type, payload: event.payload };
+    const result = await this.transport.send(orbitalName, request);
+    if (result.emittedEvents && result.emittedEvents.length > 0) {
+      for (const emitted of result.emittedEvents) {
+        this.config.eventBus.emit(`SERVER:${emitted.event}`, emitted.payload);
+        this.state.eventsReceived++;
+      }
+    }
+  }
+  async fetchOrbitals() {
+    const response = await this.fetchFn(this.config.serverUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch orbitals: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.orbitals || [];
+  }
+  // ==========================================================================
+  // Server -> Client (Polling)
+  // ==========================================================================
+  setupPolling() {
+    this.log("debug", "Polling mode - events received via forward response");
+  }
+  // ==========================================================================
+  // Server -> Client (WebSocket)
+  // ==========================================================================
+  setupWebSocket() {
+    const { serverUrl } = this.config;
+    const wsUrl = serverUrl.replace(/^http:/, "ws:").replace(/^https:/, "wss:").replace(/\/api\/orbitals$/, "/ws/orbitals");
+    try {
+      this.ws = new WebSocket(wsUrl);
+      this.ws.onopen = () => {
+        this.log("info", "WebSocket connected");
+      };
+      this.ws.onmessage = (msg) => {
+        try {
+          const data = JSON.parse(msg.data);
+          if (data.type === "event") {
+            this.config.eventBus.emit(`SERVER:${data.event}`, data.payload);
+            this.state.eventsReceived++;
+            this.log("debug", `Received server event: ${data.event}`);
+          }
+        } catch (error) {
+          this.log("error", "Failed to parse WebSocket message", error instanceof Error ? error : String(error));
+        }
+      };
+      this.ws.onerror = (error) => {
+        this.state.lastError = "WebSocket error";
+        this.log("error", "WebSocket error", error);
+      };
+      this.ws.onclose = () => {
+        this.log("info", "WebSocket closed");
+      };
+    } catch (error) {
+      this.log("error", "Failed to create WebSocket", error instanceof Error ? error : String(error));
+    }
+  }
+  // ==========================================================================
+  // Direct Methods
+  // ==========================================================================
+  /**
+   * Send an event directly to a specific orbital (bypassing EventBus)
+   */
+  async sendEvent(orbitalName, event, payload) {
+    try {
+      const result = await this.transport.send(orbitalName, { event, payload });
+      return {
+        success: result.success,
+        states: result.states,
+        emittedEvents: result.emittedEvents,
+        error: result.error
+      };
+    } catch (error) {
+      return { success: false, error: String(error) };
+    }
+  }
+  /**
+   * Get current state of an orbital's traits
+   */
+  async getOrbitalState(orbitalName) {
+    const { serverUrl } = this.config;
+    const url = `${serverUrl}/${orbitalName}`;
+    try {
+      const response = await this.fetchFn(url);
+      const data = await response.json();
+      if (data.success && data.orbital) {
+        const states = {};
+        for (const trait of data.orbital.traits) {
+          states[trait.name] = trait.currentState;
+        }
+        return { success: true, states };
+      }
+      return { success: false, error: data.error };
+    } catch (error) {
+      return { success: false, error: String(error) };
+    }
+  }
+  // ==========================================================================
+  // Utilities
+  // ==========================================================================
+  log(level, message, data) {
+    if (!this.config.debug && level === "debug") return;
+    const meta = data === void 0 ? {} : data instanceof Error ? { error: data } : { detail: typeof data === "string" ? data : JSON.stringify(data) };
+    log[level](message, meta);
+  }
+};
+function createServerBridge(config) {
+  return new ServerBridge(config);
+}
+
+export { ServerBridge, createServerBridge };

package/dist/chunk-DYOJGLIX.js

@@ -0,0 +1,25 @@
+import { findExternalInput } from '@almadar/core';
+
+// src/client/declared-input-dispatch.ts
+async function dispatchDeclaredInput(schema, orbitalName, request, send) {
+  const declared = schema ? findExternalInput(schema, orbitalName, request.targetTrait, request.event) : void 0;
+  if (!declared) {
+    return {
+      success: false,
+      transitioned: false,
+      states: {},
+      emittedEvents: [],
+      error: `'${request.event}' is not an external input of ${orbitalName}.${request.targetTrait}`,
+      rejections: [{ code: "not-an-external-input", trait: request.targetTrait, event: request.event }]
+    };
+  }
+  return send(orbitalName, {
+    event: request.event,
+    payload: request.payload ?? {},
+    targetTrait: request.targetTrait,
+    ...request.user !== void 0 ? { user: request.user } : {},
+    ...request.entityId !== void 0 ? { entityId: request.entityId } : {}
+  });
+}
+
+export { dispatchDeclaredInput };