@almadar/shell-runtime 0.1.0 → 1.0.0

package/dist/kernel/wire.d.ts

@@ -1,36 +1,69 @@
 import { KernelEvaluatorExports } from '@almadar/core';
-export { CallRoutesWire, CallSiteWire, CallerWire, HttpBody, HttpFailureWire, HttpRequestWire, HttpResponseWire, IoAnswerWire, IoReplyWire, IoRequestWire, PendingRequestWire, ResolveProgressWire, ServerProgressWire, Settled, SubstrateFailureWire } from '@almadar/core/kernel-wire';
+import { EventRequest, FrameWire } from '@almadar/core/kernel-wire';
+export { CallRoutesWire, CallSiteWire, CallerWire, IoAnswerWire, IoReplyWire, IoRequestWire, NextWire, PendingRequestWire, ResolveProgressWire, ServerProgressWire, Settled, SubstrateFailureWire } from '@almadar/core/kernel-wire';
+
+/** Fired ticks keyed by the orbital that declares them: the one a `runTick` request is addressed to. */
+type FiredByOrbital = FrameWire['fired'];
 
 /** The `Server` class of `@almadar/kernel` (wasm-bindgen), as the runtime uses it. */
 interface KernelServerHandle {
     start(orbital: string, requestJson: string): string;
     resume(flight: number, repliesJson: string): string;
+    /** The oldest request the kernel queued, started now the lane is free: a `NextWire` as JSON, or `null`. */
+    next(): string;
+    /** Whether `flight` is a dispatch parked holding the lane. */
+    holdsLane(flight: number): boolean;
+    /** A live stream of `client`'s session opened (EXEC-DIST-9); answers the id that closes it. */
+    openSessionStream(client: string): number;
+    /** The live stream `id` dropped; the kernel frees its session once all have dropped and it is quiet. */
+    closeSessionStream(id: number): boolean;
     dispatchStream(): string;
-    liveItemDelivered(itemJson: string, viewerJson: string, clientId?: string): boolean;
-    /** A row-set reference resolved for a viewer through the host-answered store; a `ResolveProgressWire` as JSON. */
-    resolveRows(refJson: string, viewerJson: string): string;
+    /** Whether a live item reaches `clientId`'s session: addressed to it and admitted by `@read` for the identity that session bound. */
+    liveItemDelivered(itemJson: string, clientId?: string): boolean;
+    /** A row-set reference resolved through the host-answered store for the identity `clientId`'s session bound (the anonymous viewer with none); a `ResolveProgressWire` as JSON. */
+    resolveRows(refJson: string, clientId?: string): string;
     resumeResolve(flight: number, repliesJson: string): string;
     abandon(flight: number): boolean;
     /** `OsGrants::allows` over the grants the registered program declares; `requirementJson` is an `OsRequirement`. */
-    osAllows(requirementJson: string): boolean;
+    osAllows(requirementJson: string, orbital?: string): boolean;
+    /** Whether `url`'s origin is one the program declares in `egress`. */
+    egressAllows(url: string): boolean;
     /** Place the program's anchored grants and arguments under the host's anchors; answers `[{ path, message }]` for what grants nothing. */
     setOsAnchors(anchorsJson: string): string;
+    /** Feed a deferred raw `os` outcome (`Settled`) into the TLS operation parked under `key`: `null`, `{ ask }` or `{ done }`. */
+    tlsComplete(key: string, outcomeJson: string): string;
     /** An `os/` call's arguments with its anchored parts resolved; a `Settled<args, OsError>` as JSON. */
     osResolveArgs(op: string, argsJson: string): string;
     inFlight(): number;
     getState(traitName: string, entityId?: string): string;
-    setDefaultUser(userJson: string): void;
     /** The kernel's mounts for a host start on `side` (`client|server|process|start`): `MountSeed[]` as JSON. */
     bootMounts(side: string): string;
     /** The kernel's mounts for a client opening `routePath`: `MountSeed[]` as JSON. */
     routeMounts(routePath: string): string;
+    /** One question about the registered program (a `ContractQuery`: the declared inputs, inbound hooks, entity owner, scoped rows): its answer as JSON. */
+    contractQuery(queryJson: string): string;
     mount(traitsJson: string): void;
     remount(traitsJson: string): void;
-    setTickMount(traitsJson: string): void;
-    /** Mock-seed the `[runtime]` entities the kernel holds itself, owner columns stamped with `viewerId` (a preview host). */
-    seedRuntimeMock(viewerId?: string): void;
+    /** Whether the kernel holds the circuit state: a client's copy of it is then taken only on a delegated leg, and any other request carrying one is refused. */
+    setStateful(stateful: boolean): void;
+    /** `client` mounted the traits (`string[]` JSON) of `orbital`: their mount-scoped ticks fire while any client holds them. */
+    mountClient(client: string, orbital: string, traitsJson: string): void;
+    unmountClient(client: string, orbital: string, traitsJson: string): void;
+    /** `client` is gone: everything it mounted is released. */
+    releaseClient(client: string): void;
+    /** Queue the tick-stamped request (an `EventRequest` as JSON) of `orbital` for the coalesced peer relay: the window length in ms as JSON when it opened one, else `null`. */
+    relayTick(orbital: string, requestJson: string): string;
+    setTickRelayInterval(intervalMs: number): void;
+    /** Every queued relay item (`LiveBroadcastItem[]` as JSON); the window closes. */
+    flushTickRelay(): string;
+    /** Whether the program declares any tick. */
+    declaresTicks(): boolean;
+    /** One pass of the kernel's tick clock at monotonic `nowMs`: the `(trait, tick)` pairs due that this server runs, keyed by orbital, as `FiredByOrbital` JSON. */
+    tickPass(nowMs: number): string;
+    tickPause(): void;
+    tickResume(): void;
+    tickPaused(): boolean;
     setCapabilities(entityType: string, queryJson: string, writeJson: string): void;
-    setMessages(localesJson: string, catalogsJson: string): void;
     /** The program (as JSON) whose declared credentials this server's credential effects manage beside its own. */
     setManagedProgram(programJson: string): void;
     lastError(): string;
@@ -41,7 +74,8 @@ interface KernelServerHandle {
 }
 /** The `Server` constructor of a kernel module. */
 interface KernelServerClass {
-    new (resolvedSchemaJson: string): KernelServerHandle;
+    /** `lazyDir`: the folder the program's `uses lazy` files sit beside; the kernel loads each on the first dispatch that reaches it (EXEC-LOAD-2). */
+    new (resolvedSchemaJson: string, lazyDir?: string): KernelServerHandle;
 }
 /** An initialised `@almadar/kernel` module: what `OrbitalServerRuntime({ engine: 'kernel' })` is handed. */
 interface KernelModule extends KernelEvaluatorExports {
@@ -50,6 +84,8 @@ interface KernelModule extends KernelEvaluatorExports {
     osGlobMatches(glob: string, path: string): boolean;
     /** `is_public_address`: the rule an outbound host name must pass. */
     isPublicAddress(ip: string): boolean;
+    /** One `ContractQuery` (as JSON) answered for a host with no registered program: the kernel's own answer on an empty kernel, as JSON. */
+    contractQueryWithoutProgram(queryJson: string): string;
     /** The `os/` operations whose keyed call may defer its completion (`OsOp::defers_completion`), as a JSON array of names. */
     osDeferringOps(): string;
     /** The `os/` operations whose keyed call is a stream (`OsOp::is_stream`), as a JSON array of names. */
@@ -59,8 +95,10 @@ interface KernelModule extends KernelEvaluatorExports {
     substrateCompletionEvent(siteJson: string, key: string, op: string, argsJson: string, outcomeJson: string): string;
     /** Whether the Chrome match pattern matches the URL: the one rule a browser-tab host filters tabs with. */
     tabUrlMatches(pattern: string, url: string): boolean;
+    /** The typed event request a `program/dispatch` call names (`EventRequest::from_dispatch`); a record that is no event request throws the reason. */
+    parseEventRequest(payloadJson: string, optionsJson: string): EventRequest;
     /** Installs the language data (`@almadar/core/language-data` `LanguageBundle` as JSON) for a host with no `node_modules`; the first install wins. */
     installLanguage(bundleJson: string): void;
 }
 
-export type { KernelModule, KernelServerClass, KernelServerHandle };
+export type { FiredByOrbital, KernelModule, KernelServerClass, KernelServerHandle };

package/dist/loader/fetch-loader.d.ts

@@ -0,0 +1,26 @@
+import { SchemaLoader, LoadResult, LoadedSchema, LoadedOrbital } from './schema-loader.js';
+import '@almadar/core';
+
+/**
+ * A `SchemaLoader` over HTTP: a browser client fetches the `.orb` of a lazy page (`uses lazy`) from beside the program
+ * it booted, at the page's `orbRef` resolved against the importer's URL (EXEC-LOAD-2: a browser client opens lazy pages
+ * through its own loader).
+ *
+ * @packageDocumentation
+ */
+
+declare class FetchSchemaLoader implements SchemaLoader {
+    private readonly base;
+    private readonly cache;
+    /** `base`: the URL relative imports resolve against when no importer is named (the page's own URL by default). */
+    constructor(base: string);
+    resolvePath(importPath: string, fromPath?: string): LoadResult<string>;
+    load(importPath: string, fromPath?: string): Promise<LoadResult<LoadedSchema>>;
+    loadOrbital(importPath: string, orbitalName?: string, fromPath?: string): Promise<LoadResult<LoadedOrbital>>;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+    };
+}
+
+export { FetchSchemaLoader };

package/dist/loader/fetch-loader.js

@@ -0,0 +1 @@
+export { FetchSchemaLoader } from '../chunk-57SBCUSM.js';

package/dist/loader/lazy-page.js

@@ -1,2 +1 @@
 export { loadLazyPage } from '../chunk-XXWNMJI6.js';
-import '../chunk-MLKGABMK.js';

package/dist/loader/schema-loader.d.ts

@@ -6,7 +6,6 @@ import { OrbitalSchema, Orbital, DeclaredTraitConfig } from '@almadar/core';
  * Abstract interface for loading OrbitalSchema files from various sources.
  * Implementations exist for:
  * - FileSystemLoader (Node.js) - uses fs module
- * - HttpLoader (Browser) - uses fetch API
  * - UnifiedLoader (Auto-detect) - routes to appropriate loader
  *
  * @packageDocumentation
@@ -68,17 +67,6 @@ interface BaseLoaderOptions {
     /** Scoped package roots (e.g., { "@game-lib": "/path/to/lib" }) */
     scopedPaths?: Record<string, string>;
 }
-/**
- * Options for HTTP loading.
- */
-interface HttpLoaderOptions extends BaseLoaderOptions {
-    /** Default fetch options */
-    fetchOptions?: RequestInit;
-    /** Request timeout in milliseconds */
-    timeout?: number;
-    /** Whether to use credentials (cookies, auth headers) */
-    credentials?: RequestCredentials;
-}
 /**
  * Abstract interface for schema loaders.
  *
@@ -92,10 +80,6 @@ interface HttpLoaderOptions extends BaseLoaderOptions {
  * const loader: SchemaLoader = new FileSystemLoader({ basePath: "/schemas" });
  * const result = await loader.load("./my-schema.orb");
  *
- * // Using HttpLoader (Browser)
- * const loader: SchemaLoader = new HttpLoader({ basePath: "/api/schemas" });
- * const result = await loader.load("./my-schema.orb");
- *
  * // Using UnifiedLoader (auto-detect)
  * const loader: SchemaLoader = createUnifiedLoader({ basePath: "/schemas" });
  * const result = await loader.load("./my-schema.orb");
@@ -157,4 +141,4 @@ interface ImportChainLike {
     clone(): ImportChainLike;
 }
 
-export type { BaseLoaderOptions, HttpLoaderOptions, ImportChainLike, LoadResult, LoadedOrbital, LoadedSchema, SchemaLoader };
+export type { BaseLoaderOptions, ImportChainLike, LoadResult, LoadedOrbital, LoadedSchema, SchemaLoader };

package/dist/persistence/native-memory.js

@@ -1,2 +1 @@
 export { NativeMemoryPersistenceAdapter, NativeMemoryWriteError } from '../chunk-7SDV3QWR.js';
-import '../chunk-MLKGABMK.js';

package/dist/runtime/entities/declaredCollections.d.ts

@@ -0,0 +1,6 @@
+import { PersistenceAdapter, Entity } from '@almadar/core';
+
+/** Tells the store each server-persisted entity's declared `[persistent: tbl]` collection (EXEC-STORE-1). */
+declare function bindDeclaredCollections(store: PersistenceAdapter, entities: readonly Entity[]): void;
+
+export { bindDeclaredCollections };

package/dist/runtime/entities/declaredCollections.js

@@ -0,0 +1 @@
+export { bindDeclaredCollections } from '../../chunk-BAS26HBN.js';

package/dist/runtime/evaluation/local-store-transport.d.ts

@@ -1,23 +1,17 @@
-import { OrbitalSchema, PersistenceAdapter, OnDeviceModelPorts, BrowserTabPort, MessageCatalogs, UserContext, RowSetRef, RowQueryPage } from '@almadar/core';
+import { OrbitalSchema, PersistenceAdapter, OnDeviceModelPorts, BrowserTabPort, RowSetRef, RowQueryPage } from '@almadar/core';
 import { EffectHandlers } from '../types.js';
 import { KernelEngine } from '../../kernel/engine.js';
 import { KernelHostPorts } from '../../kernel/host.js';
-import { HttpPorts } from '../../kernel/http.js';
+import { OsHostPort } from '../../kernel/os-port.js';
+import { SecretPorts } from '../../kernel/secret-ports.js';
 import { KernelModule } from '../../kernel/wire.js';
 import { EventTransport } from '../../client/EventTransport.js';
 import '../../service/default-call-service.js';
 import '../../service/service-provider.js';
 import '../../kernel/program-effects.js';
-import '../effects/composition/compose-behaviors.js';
-import '../effects/composition/event-wiring.js';
-import '../effects/composition/layout-strategy.js';
-import '../effects/composition/pipe.js';
-import '../../effects/in-flight-calls.js';
-import '../../kernel/beacon.js';
-import '../../credentials/store.js';
-import '../../kernel/decode.js';
 import '@almadar/core/kernel-wire';
-import '../../kernel/os-port.js';
+import '../../effects/in-flight-calls.js';
+import '../../credentials/vault.js';
 
 /**
  * An in-process transport over a local store: every request runs on the kernel opened over that store
@@ -26,10 +20,8 @@ import '../../kernel/os-port.js';
  */
 
 interface LocalKernelOptions {
-    /** The initialised `@almadar/kernel` module. */
+    /** The initialised `@almadar/kernel` module with its language already installed (`loadBrowserKernel`): opening a kernel installs nothing. */
     kernel: KernelModule;
-    /** The language bundle as JSON (`LanguageBundle`), installed into `kernel` before it opens: a browser has no `node_modules` to read it from. */
-    language: string;
     schema: OrbitalSchema;
     /** Every row the kernel reads and writes (`localStorePersistence` over a browser store). */
     persistence: PersistenceAdapter;
@@ -40,11 +32,12 @@ interface LocalKernelOptions {
     /** Where a follow-on call's outcome is dispatched; absent, nowhere. */
     deferCallOutcome?: KernelHostPorts['deferCallOutcome'];
     pageFacts?: KernelHostPorts['pageFacts'];
-    http?: HttpPorts;
+    hostActions?: KernelHostPorts['hostActions'];
+    secretPorts?: SecretPorts;
     onDevice?: OnDeviceModelPorts;
     tabs?: BrowserTabPort;
-    /** The program's message catalogs, so `i18n/t` resolves for the request's locale. */
-    messages?: MessageCatalogs;
+    /** The host's `os` port (`createFetchOsHost` in a browser); absent, every `os` ask is denied. */
+    os?: OsHostPort;
 }
 /** A local store's rows as the kernel holds them: browser-stored entities in `store`, every other entity in `memory` (a native `MemoryStore` adapter). */
 declare function localStorePersistence(schema: OrbitalSchema, store: PersistenceAdapter, memory: PersistenceAdapter): PersistenceAdapter;
@@ -53,16 +46,14 @@ declare function openLocalKernel(options: LocalKernelOptions): KernelEngine;
 interface LocalStoreTransportOptions {
     /** The kernel the requests run on (`openLocalKernel`), or its promise while the kernel module loads. */
     kernelEngine: KernelEngine | Promise<KernelEngine>;
-    /** The viewer every request runs as, or its promise while the host resolves it (a mock store's seeded persona). */
-    user?: UserContext | Promise<UserContext | undefined>;
-    /** Releases the host's request queue while a `call-service` awaits its provider. */
-    outsideEventQueue?: <T>(work: () => Promise<T>) => Promise<T>;
     /** The program the kernel runs; given, the transport resolves row-set references on that kernel. */
     schema?: OrbitalSchema;
+    /** The page's locale, read per request: a request naming none runs in it, as a server request carries its viewer's. */
+    locale?: () => string | undefined;
 }
 declare function createLocalStoreTransport(options: LocalStoreTransportOptions): EventTransport;
-/** `reference` resolved on a local kernel for `user`: the kernel applies the viewer's `@read`, the host answers its row reads. */
-declare function resolveLocalRows(engine: KernelEngine, schema: OrbitalSchema, user: UserContext | undefined, reference: RowSetRef): Promise<RowQueryPage>;
+/** `reference` resolved on a local kernel: the kernel applies the session identity's `@read`, the host answers its row reads. */
+declare function resolveLocalRows(engine: KernelEngine, reference: RowSetRef): Promise<RowQueryPage>;
 
 export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows };
 export type { LocalKernelOptions, LocalStoreTransportOptions };

package/dist/runtime/evaluation/local-store-transport.js

@@ -1,18 +1,14 @@
-export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows } from '../../chunk-VNMG7NKY.js';
+export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows } from '../../chunk-MU335ZA4.js';
 import '../../chunk-4SEK5ER2.js';
 import '../../chunk-UBN5JJKZ.js';
 import '../../chunk-O57GKTYU.js';
-import '../../chunk-CPSQXEJ6.js';
-import '../../chunk-SAS5KKCR.js';
-import '../../chunk-D4XJTBLB.js';
-import '../../chunk-NATGCIVM.js';
-import '../../chunk-HNOAZWFH.js';
-import '../../chunk-53IPZXDP.js';
-import '../../chunk-YO4LWS3I.js';
-import '../../chunk-MZKIL5IN.js';
+import '../../chunk-I3TKINSO.js';
+import '../../chunk-NU6LVKGS.js';
+import '../../chunk-X6W44WHO.js';
+import '../../chunk-7WB6VWRK.js';
+import '../../chunk-WGCWJOT2.js';
+import '../../chunk-ZUSM4VW4.js';
 import '../../chunk-FWA5K7Q2.js';
-import '../../chunk-VMOBW7RK.js';
-import '../../chunk-RBUMDYFS.js';
 import '../../chunk-HLOUDLPI.js';
-import '../../chunk-QELZ6TEJ.js';
-import '../../chunk-MLKGABMK.js';
+import '../../chunk-MZKIL5IN.js';
+import '../../chunk-UD2CXYSJ.js';

package/dist/runtime/evaluation/residence-transport.d.ts

@@ -1,13 +1,13 @@
 import { EventTransport } from '../../client/EventTransport.js';
-import { TraitIndex } from '@almadar/core';
+import '@almadar/core';
 
 interface ResidenceTransportOptions {
     /** In-process transport over the browser store. */
     local: EventTransport;
     /** The server; absent on a static host. */
     remote?: EventTransport;
-    /** The program's entities, for where a row-set reference's rows live. */
-    traitIndex: TraitIndex;
+    /** The program's browser-stored entities (the kernel's `programSurface`): a row-set reference to one of them is resolved in-process. */
+    browserEntities: ReadonlySet<string>;
 }
 declare function createResidenceTransport(options: ResidenceTransportOptions): EventTransport;
 

package/dist/runtime/evaluation/residence-transport.js

@@ -1,2 +1 @@
-export { createResidenceTransport } from '../../chunk-UJHOUZAL.js';
-import '../../chunk-MLKGABMK.js';
+export { createResidenceTransport } from '../../chunk-V4EMDPCO.js';

package/dist/runtime/evaluation/routed-persistence.js

@@ -1,2 +1 @@
 export { routeByEntity } from '../../chunk-O57GKTYU.js';
-import '../../chunk-MLKGABMK.js';

package/dist/runtime/events/identity/routing.d.ts

@@ -1,4 +1,4 @@
-import { TraitId, OrbitalId, EventId } from '@almadar/core';
+import { EventId } from '@almadar/core';
 
 /**
  * Identity-keyed routing (Almadar Rabit V4, Phase 4 — interpreter path).
@@ -29,56 +29,5 @@ import { TraitId, OrbitalId, EventId } from '@almadar/core';
  * wildcard listeners are untouched.
  */
 declare function eventRouteKey(eventName: string, eventId?: EventId | string): string;
-/** Structured `listens {}` source, carrying V4 dual-carry ids when present. */
-type ListenSourceDescriptor = {
-    kind: 'any';
-} | {
-    kind: 'trait';
-    trait: string;
-    traitId?: TraitId;
-} | {
-    kind: 'orbital';
-    orbital: string;
-    trait: string;
-    orbitalId?: OrbitalId;
-    traitId?: TraitId;
-};
-/**
- * The subset of a bus event's `source` metadata the matcher reads. Kept
- * structural (no index signature) so `BusEventSource` assigns to it cleanly.
- */
-interface RouteSourceMeta {
-    orbital?: string;
-    orbitalId?: OrbitalId;
-    trait?: string;
-    traitId?: TraitId;
-}
-/**
- * Build a source-scope matcher for a `listens {}` entry.
- *
- * ID-first: when the listen source carries the id(s) for its scope, the
- * matcher compares ids ONLY (exact-match, rename-proof). Otherwise it
- * compares names against `listenerOrbital` — the exact legacy predicate.
- * No name-similarity, ever: an id present on one side but absent on the
- * other is a mismatch, never a fuzzy fallback.
- */
-declare function buildSourceMatcher(src: ListenSourceDescriptor, listenerOrbital: string): (source: RouteSourceMeta | undefined) => boolean;
-/**
- * Parse one `listens {}` entry into its bare event name + source matcher.
- * Relocated here (was module-private to `OrbitalServerRuntime.ts`) so the
- * stateless `@almadar-io/playground-runtime` path can reuse the EXACT same
- * matching predicate for its own cross-orbital cascade (Fix A2) instead of
- * a second, divergent copy — this function only ever depended on
- * `ListenSourceDescriptor`/`buildSourceMatcher`, both already local to this
- * module.
- */
-declare function parseListenSource(listener: {
-    event: string;
-    source?: ListenSourceDescriptor;
-}, listenerOrbital: string): {
-    bareEvent: string;
-    matcher: (source: RouteSourceMeta | undefined) => boolean;
-};
 
-export { buildSourceMatcher, eventRouteKey, parseListenSource };
-export type { ListenSourceDescriptor, RouteSourceMeta };
+export { eventRouteKey };

package/dist/runtime/events/identity/routing.js

@@ -1,2 +1 @@
-export { buildSourceMatcher, eventRouteKey, parseListenSource } from '../../../chunk-IHQLE5M7.js';
-import '../../../chunk-MLKGABMK.js';
+export { eventRouteKey } from '../../../chunk-BY5G4225.js';