@almadar/shell-node 0.0.0-stage → 1.0.0

package/dist/OrbitalServerRuntime.d.ts

@@ -0,0 +1,473 @@
+import { EventPayload, EffectHandlers, EvaluationContextExtensions, KernelModule, SecretPortsOptions, OsGrantPort, OsHostPort, EventBus, TraitState } from '@almadar/shell-runtime';
+import { EventRequest, EventResponse, BusEventSource, OrbitalDefinition, PersistenceAdapter, OrbitalSchema, RowSetRef, RowQueryPage, ExternalInput, UserContext, ServiceHostPorts, DispatchRequestOutcome, ExternalInputRequest, ClientEffectTuple, InboundDelivery, InboundAnswer } from '@almadar/core';
+export { ClientEffectTuple, ClientNavigateBackTuple, ClientNavigateTuple, ClientRenderUITuple, EventRequest, EventResponse, TransitionRejection } from '@almadar/core';
+
+/**
+ * OrbitalServerRuntime: the Node host that runs a registered program on the kernel. It answers the kernel's asks
+ * (rows, services, secrets, `os` through the given os host, live streams), drives its ticks and mounts; it serves no
+ * HTTP routes (a served program composes std-http-server for that).
+ *
+ * @packageDocumentation
+ */
+
+/** @deprecated Use OrbitalSchema from @almadar/core */
+type RuntimeOrbitalSchema = OrbitalSchema;
+/** @deprecated Use OrbitalDefinition from @almadar/core */
+type RuntimeOrbital = OrbitalDefinition;
+/**
+ * Incremental-push item streamed to an SSE client mid-dispatch (an emitted
+ * event or a client effect), before the response resolves.
+ */
+type PushItem = {
+    type: 'event';
+    data: {
+        event: string;
+        payload?: EventPayload;
+        source?: BusEventSource;
+    };
+    timestamp?: number;
+} | {
+    type: 'effect';
+    data: ClientEffectTuple;
+    timestamp?: number;
+};
+/**
+ * Registered orbital with runtime state
+ */
+interface RegisteredOrbital {
+    schema: OrbitalDefinition;
+}
+/**
+ * One persist-envelope success emit, handed to the live-broadcast sink
+ * (`setLiveBroadcastSink`). Fired only from the `persist` effect's
+ * `emit:{success}` envelope (batch and single-op) — never from the generic
+ * emit funnel — so transport layers can fan it out to every OTHER
+ * connected client without matching on event names.
+ */
+interface LiveBroadcastItem {
+    event: string;
+    payload?: EventPayload;
+    source: BusEventSource;
+    /** `clientId` of the request that produced this emit. */
+    originClientId?: string;
+    /**
+     * `peers`: every OTHER client (persist envelopes, tick relay). `origin`:
+     * only the requesting client, while its request is still running (a
+     * `call-service`'s live `emit.onMessage`).
+     */
+    target: 'peers' | 'origin';
+}
+/**
+ * The result of a dispatch the host ran on its own — a follow-on step's `call-service`
+ * outcome, run after the request that started the call had answered — for the tab that
+ * asked (`originClientId`). Handed to the host-dispatch sink (`setHostDispatchSink`).
+ */
+interface HostDispatchItem {
+    orbitalName: string;
+    request: EventRequest;
+    response: EventResponse;
+    originClientId?: string;
+}
+/**
+ * Loader configuration for resolving `uses` imports
+ */
+interface LoaderConfig {
+    /** Where `orb` resolves a registered program's imports from, when no `programHost` names it. */
+    basePath: string;
+}
+/**
+ * Runtime configuration
+ */
+interface OrbitalServerRuntimeConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Snapshot cadence (ms) for relaying tick-stamped broadcasts to other
+     * clients — newest-per-(client, orbital, event) wins between flushes
+     * (T6, docs/Almadar_Tick_Loop.md §3a). Default 50 (≈20Hz).
+     */
+    tickRelayIntervalMs?: number;
+    /** Custom effect handlers (for integrating with your data layer) */
+    effectHandlers?: Partial<EffectHandlers>;
+    /** Persistence adapter for entity data */
+    persistence?: PersistenceAdapter;
+    /** Where a registered program with imports is resolved from (`orb resolve`). */
+    loaderConfig?: LoaderConfig;
+    /**
+     * Additional fields to spread onto every EvaluationContext.
+     * Use this to inject module contexts (e.g., { agent: AgentContext }).
+     * The evaluator dispatches agent/* operators to ctx.agent.
+     */
+    contextExtensions?: EvaluationContextExtensions;
+    /**
+     * The program host behind behavior/catalog|describe|source and
+     * program/read|print|eval: the project root `orb` runs from. Absent means
+     * those effects fail explicitly ("no program host configured").
+     */
+    programHost?: {
+        cwd: string;
+        orbBin?: string;
+    };
+    /**
+     * The initialised `@almadar/kernel` module that decides execution and whose I/O this runtime answers with its
+     * persistence, service and program-host adapters. Absent, the runtime loads the installed `@almadar/kernel` itself
+     * (`loadInstalledKernel`) when a program is first registered.
+     */
+    kernel?: KernelModule;
+    /**
+     * What the kernel's secret, random and credential asks run on: optionally the secret store, the CSPRNG and the
+     * credential administration port. Absent, those asks fail as unavailable.
+     */
+    secretPorts?: SecretPortsOptions;
+    /**
+     * Builds the `os` host of the kernel engine from the grant port backed by the kernel (`createNodeOsHost` from
+     * `@almadar/shell-node`). Absent, every `os` ask is denied, as the native host does with none.
+     */
+    osHost?: (grants: OsGrantPort) => OsHostPort;
+    /** The clock the kernel's `clock` ask is answered from, in epoch milliseconds; absent, the system clock. */
+    clock?: () => number;
+}
+
+/**
+ * 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.
+ */
+/** A program with imports registered where `orb` cannot run (a browser): resolve it first (`orb resolve`). */
+declare class UnresolvedProgramError extends Error {
+    constructor(schemaName: string);
+}
+/** What `register` takes beside the schema: the folder its `uses lazy` behaviors sit beside (EXEC-LOAD-1). The program carries its own messages. */
+interface RegisterOptions {
+    lazyDir?: string;
+}
+declare class OrbitalServerRuntime {
+    protected orbitals: Map<string, RegisteredOrbital>;
+    private eventBus;
+    private config;
+    /** The row store a host-supplied `persistence` replaces: the kernel's own `MemoryStore`, opened by the first `register()`. */
+    private 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(): PersistenceAdapter;
+    /** The kernel running the registered program; null before a program is registered. */
+    private kernelEngine;
+    /** What the kernel holds of every trait of the registered program, read once when the kernel opens. */
+    private programSurface;
+    /** The `os` handles of the program the kernel runs; closed when that program is replaced, reset or dropped. */
+    private kernelOs;
+    /** Drives the kernel's one tick clock: every pass asks `KernelEngine.tickPass` which ticks are due. */
+    private tickTimer;
+    private programHandlersPromise;
+    private resolvedSchema;
+    /** The folder the program's lazy files sit beside; the pages that name them are on `resolvedSchema.lazyPages`. */
+    private lazyDir;
+    /** Wired by the hosting server (e.g. the playground SSE endpoint) via `setLiveBroadcastSink`. */
+    private readonly liveSubscribers;
+    private liveBroadcastSink;
+    private hostDispatchSink;
+    /** The one-shot timer that flushes the kernel's coalesced tick relay window. */
+    private tickRelayTimer;
+    constructor(config: OrbitalServerRuntimeConfig);
+    /**
+     * 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.
+     */
+    private ensureProgramHandlers;
+    /**
+     * 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.
+     */
+    private registrationEpoch;
+    /**
+     * 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).
+     */
+    private registrationMutationDepth;
+    register(schema: OrbitalSchema, options?: RegisterOptions): Promise<void>;
+    private doRegister;
+    /** The kernel's own row store, opened once in the register phase when the host supplied none. */
+    private openOwnedStore;
+    /**
+     * 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>;
+    /** A program with imports resolved by `orb` from the configured base path (Node only: the one resolver is the compiler). */
+    private resolveWithOrb;
+    /**
+     * Register a single orbital
+     */
+    private registerOrbitalAsync;
+    /** The adapters the kernel's I/O is answered with: this runtime's persistence, services and program host. */
+    private secretPorts;
+    private kernelPorts;
+    /** One live message of a running `call-service`, stamped as its calling trait, to the requesting tab only. */
+    private deliverLiveMessage;
+    /** The traits of one orbital as the kernel holds them. */
+    private traitsOf;
+    /** The project root this runtime hands `orb` and the kernel's language data: the program host's cwd, else the loader base path. */
+    private programRoot;
+    /** The kernel module this runtime runs on: the one the host handed in, else the installed `@almadar/kernel`. */
+    private kernelModule;
+    /** (Re)open the kernel on the program just registered. */
+    private openKernel;
+    /** Run the kernel's boot mounts for the server side (EXEC-ENDPOINT-3): the host sends what the kernel lists and chooses nothing. */
+    private mountBootEndpoints;
+    /** What answers the declared contract: the registered program's kernel, else the kernel's own program-less answers, which refuse every input and hook. */
+    private contractEngine;
+    private requireKernelEngine;
+    /** Ask the kernel's clock which ticks are due and start each as a `runTick` request to the orbital it names. */
+    private tickPass;
+    /** Run the kernel's clock on this host's timer when the program declares a tick. */
+    private restartTickClock;
+    /** A tick: the host owns the timer, the kernel decides whether and over which rows it fires. */
+    private executeTick;
+    /**
+     * Stop the host's timers
+     */
+    private cleanupTicks;
+    /**
+     * Unregister all orbitals and clean up
+     */
+    unregisterAll(): void;
+    /**
+     * 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.
+     */
+    private bracketAls;
+    private ensureBracketAls;
+    withRegistrationMutation<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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(): void;
+    /**
+     * 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: (item: LiveBroadcastItem) => void): void;
+    private publishLiveItem;
+    /** Wire where a host-run dispatch's result goes (see `HostDispatchItem`); a fresh call replaces the previous sink. */
+    setHostDispatchSink(sink: (item: HostDispatchItem) => void): void;
+    /** Run a follow-on step's call outcome as its own dispatch, and hand its result to the host-dispatch sink. */
+    private runDeferredOutcome;
+    /**
+     * 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.
+     */
+    private queueTickRelay;
+    private flushTickRelay;
+    /**
+     * `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`.
+     */
+    resolveRows(reference: RowSetRef, clientId: string | undefined): Promise<RowQueryPage>;
+    /**
+     * 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.
+     */
+    private resolveRegisteredOrbital;
+    /** 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). */
+    private loadLazyOrbital;
+    /** The program's declared external inputs: what an outside client may send which trait. */
+    listExternalInputs(): ExternalInput[];
+    /**
+     * 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: {
+        orbital: string;
+        trait: string;
+    }, user: UserContext | undefined, message?: (payload: EventPayload) => void, assertReentry?: () => void): ServiceHostPorts;
+    /**
+     * 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.
+     */
+    dispatchEventRequest(orbital: string, parsed: EventRequest, input: boolean, stream?: boolean): Promise<DispatchRequestOutcome>;
+    dispatchExternalInput(orbitalName: string, request: ExternalInputRequest, onPush?: (item: PushItem) => void): Promise<EventResponse>;
+    /**
+     * 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: string, request: Pick<EventRequest, 'event' | 'targetTrait'>): EventResponse | undefined;
+    deliverInbound(name: string, delivery: InboundDelivery, onPush?: (item: PushItem) => void): Promise<InboundAnswer>;
+    processOrbitalEvent(orbitalName: string, request: EventRequest, onPush?: (item: PushItem) => void): Promise<EventResponse>;
+    /**
+     * One request evaluated on the kernel, which orders it among every other (EXEC-CONC-2), then its emits relayed
+     * to the host sinks.
+     */
+    private evaluateForOrbital;
+    /**
+     * 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.
+     */
+    private publishKernelResponse;
+    /** This app's in-flight keyed `call-service`s, shared by every transition it runs (`cancel-call`). */
+    private readonly inFlightCalls;
+    /**
+     * Get the event bus for manual event emission
+     */
+    getEventBus(): EventBus;
+    /**
+     * Get state for a specific orbital/trait
+     */
+    getState(orbitalName: string, traitName?: string): TraitState | Record<string, TraitState> | undefined;
+    /**
+     * List registered orbitals
+     */
+    listOrbitals(): string[];
+    /**
+     * Check if an orbital is registered
+     */
+    hasOrbital(name: string): boolean;
+}
+
+export { OrbitalServerRuntime, UnresolvedProgramError };
+export type { HostDispatchItem, LiveBroadcastItem, LoaderConfig, OrbitalServerRuntimeConfig, PushItem, RegisterOptions, RegisteredOrbital, RuntimeOrbital, RuntimeOrbitalSchema };

package/dist/OrbitalServerRuntime.js

@@ -0,0 +1,3 @@
+export { OrbitalServerRuntime, UnresolvedProgramError } from './chunk-3PNZYEZQ.js';
+import './chunk-VQVAHUAX.js';
+import './chunk-EEYGL7AB.js';