@almadar/shell-runtime 0.0.0-stage → 1.0.0

package/dist/kernel/program-effects.d.ts

@@ -0,0 +1,48 @@
+import { ProgramInspection, CatalogEntry, TraitDescription, BehaviorDescription, OrbitalSchema, EvaluatedProgram, ProgramValidationIssue, DependencyGraph, EventPayload } from '@almadar/core';
+import { ProveReport, OsGrantsReport, PlayedStep } from '@almadar/core/kernel-wire';
+export { PlayedStep } from '@almadar/core/kernel-wire';
+
+/** The effects the language trio routes to this host. */
+declare const PROGRAM_EFFECTS: readonly ["behavior/catalog", "behavior/describe", "behavior/source", "behavior/resolve", "behavior/dependencies", "program/read", "program/print", "program/eval", "program/validate", "program/prove", "program/os-grants", "program/compose", "program/step"];
+type ProgramEffectName = (typeof PROGRAM_EFFECTS)[number];
+/** Narrow an effect head to one this host runs. */
+declare function isProgramEffect(name: string): name is ProgramEffectName;
+/** What `program/validate` returns. */
+interface ProgramValidationReport {
+    readonly valid: boolean;
+    readonly errors: readonly ProgramValidationIssue[];
+    readonly warnings: readonly ProgramValidationIssue[];
+}
+/** One transition a host asks to play: the trait, the state it plays from, and the event with its payload. */
+interface StepRequest {
+    orbital: string;
+    trait: string;
+    from: string;
+    event: string;
+    payload: EventPayload;
+    /** Fields merged into the trait's entity row before the event. */
+    entity?: EventPayload;
+    /** Knob values over the trait's declared config defaults, for this request's trait only. */
+    config?: EventPayload;
+    /** The ms-epoch `@now` the step's dispatch reads, in place of the wall clock. */
+    now?: number;
+    /** A live call's cutoff: an open call still running after this many ms is cancelled. */
+    settleMs?: number;
+    /** Test-only: the verified identity the replay kernel binds for this step (`@user`); absent is the anonymous viewer. */
+    identity?: {
+        subject: string;
+        claims: EventPayload;
+    };
+}
+/** The outcome of one program effect: the value for `{ result }`, or the failure (`errors` for eval's validator issues). */
+type ProgramEffectOutcome = {
+    readonly ok: true;
+    readonly result: ProgramInspection | CatalogEntry[] | TraitDescription | BehaviorDescription | OrbitalSchema | string | EvaluatedProgram | ProgramValidationReport | ProveReport | OsGrantsReport | DependencyGraph | PlayedStep[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly errors?: readonly ProgramValidationIssue[];
+};
+
+export { PROGRAM_EFFECTS, isProgramEffect };
+export type { ProgramEffectName, ProgramEffectOutcome, ProgramValidationReport, StepRequest };

package/dist/kernel/program-effects.js

@@ -0,0 +1 @@
+export { PROGRAM_EFFECTS, isProgramEffect } from '../chunk-WGCWJOT2.js';

package/dist/kernel/secret-ports.d.ts

@@ -0,0 +1,139 @@
+import { RuntimeValue, CredentialPayload } from '@almadar/core';
+import { TokenEndpointPost, CredentialVault } from '../credentials/vault.js';
+import { CredentialGrantWire, CredentialStanding, ConnectFailure } from '@almadar/core/kernel-wire';
+
+/**
+ * The host ports of the kernel's secret, random and credential asks: the secret store, the CSPRNG and the credential
+ * administration port. The `http` effect is retired (HTTP/1.1 is `.lolo` over `os/*`), so nothing here moves HTTP bytes.
+ */
+
+/**
+ * The host's secret store: a credential NAME in, its value out; `set` keeps a minted value for `ttlMs`.
+ * `principal` is the signed-in user's id for a user-scoped credential (the kernel sets it from the dispatch's `@user`,
+ * never the program); absent, the credential is app-wide.
+ */
+interface SecretStore {
+    get(name: string, principal?: string): Promise<string | undefined>;
+    /** `ttlMs` of 0 forgets the value. */
+    set(name: string, value: string, ttlMs: number, principal?: string): Promise<void>;
+    /** Replace the stored credential with `value`, durably (a rotated refresh token). A host without one cannot rotate. */
+    rotate?(name: string, value: string, principal?: string): Promise<void>;
+    /** Drop the credential, the minted value and the stored one. */
+    forget(name: string, principal?: string): Promise<void>;
+    /** Keep `value` as the credential until it is forgotten, creating it when absent: unlike `rotate` it needs no existing entry. `label` is a non-secret account name stored beside it, never the value. */
+    persist?(name: string, value: string, principal?: string, label?: string): Promise<void>;
+    /** The non-secret account label stored beside the credential; absent when its row carries none. */
+    label?(name: string, principal?: string): Promise<string | undefined>;
+    /** Whether `persist` keeps a value on this host. */
+    durable?(): Promise<boolean>;
+}
+/** The credential-store key of one user's credential. */
+declare function userCredentialKey(principal: string, name: string): string;
+/** CSPRNG output: `bytes` random bytes. */
+type RandomSource = (bytes: number) => Uint8Array;
+/**
+ * The host's raw credential store and mode flag, answered to the kernel's `credentialStore*` and `credentialMode*`
+ * asks. It decides nothing: the role gate, the declared-name check, the masking and the mode check are the kernel's.
+ */
+interface CredentialAdminPort {
+    /** Whether the store can encrypt and the service and name of every stored row; `null` when the host holds no store. */
+    list(): Promise<{
+        enabled: boolean;
+        entries: Array<{
+            service: string;
+            name: string;
+        }>;
+    } | null>;
+    /** The stored value of credential `name`, from the store only. */
+    read(name: string): Promise<string | null>;
+    write(service: string, name: string, value: string): Promise<void>;
+    /** Whether a stored row existed. */
+    remove(name: string): Promise<boolean>;
+    rotate(): Promise<{
+        rotated: number;
+        alreadyCurrent: number;
+        unreadable: number;
+    }>;
+    /** The mode flag; `null` when the host keeps none. */
+    mode(): Promise<string | null>;
+    /** Switch the flag; the host may refuse. The mode in force afterwards. */
+    setMode(mode: string): Promise<string>;
+}
+/** The tails of the named variables this host's own environment holds: `last4` only from eight characters up, never a value. */
+type EnvTailsPort = (names: readonly string[]) => Array<{
+    name: string;
+    last4?: string;
+}>;
+/** The environment tails of `env`: a name it holds non-empty, with the last four characters of a value of eight or more. */
+declare function envTailsOf(env: Readonly<Record<string, string | undefined>>): EnvTailsPort;
+/** The host's answer to a `credentialConnect` ask: the kernel's store builds the exchange and settles it, the host only sends it. */
+type CredentialConnectPort = (grant: CredentialGrantWire) => Promise<{
+    ok: CredentialStanding;
+} | {
+    error: ConnectFailure;
+}>;
+interface SecretPorts {
+    /** The host CSPRNG `random-bytes` and the driver's `Random` ask draw from. */
+    random: RandomSource;
+    secrets: SecretStore;
+    /** The credential store and mode flag the credential administration effects ask; absent, those asks fail unavailable. */
+    credentials?: CredentialAdminPort;
+    /** The host's own environment, for `credential-list`; absent, the host answers `unsupported` (a browser reads none). */
+    env?: EnvTailsPort;
+    /** Carries a `credentialConnect`; absent, the ask answers `unavailable`. */
+    connect?: CredentialConnectPort;
+}
+interface SecretPortsOptions {
+    random?: RandomSource;
+    secrets?: SecretStore;
+    /** Defaults to the installed credential store and mode flag. */
+    credentials?: CredentialAdminPort;
+    /** Defaults to the process environment. */
+    env?: EnvTailsPort;
+    /** The host's POST to a token endpoint; with it the credential store connects and refreshes OAuth credentials, without it neither is attempted. */
+    tokenPost?: TokenEndpointPost;
+}
+/** Where the secrets' durable credentials live: the store a host installed, and how a name resolves through it. */
+interface SecretStoreHost {
+    store(): Promise<CredentialVault | null>;
+    resolve(name: string, principal: string | undefined): Promise<string | undefined>;
+}
+/**
+ * The secrets of a host: minted values with an expiry (a memory tier that never reaches the rows), then the credential vault
+ * the host holds (by default the one the host installed). Everything durable is the kernel's: `rotate`, `persist`, `label`,
+ * and `forget`.
+ */
+declare function createSecretStore(now?: () => number, host?: SecretStoreHost, tokenPost?: TokenEndpointPost): SecretStore;
+/** `credentialConnect` over the installed credential store and the host's token POST. */
+declare function createCredentialConnectPort(post: TokenEndpointPost): CredentialConnectPort;
+/** The credential store and mode flag the host installed, as the kernel's raw asks. */
+declare function createCredentialAdminPort(): CredentialAdminPort;
+/** Bytes from the platform CSPRNG. */
+declare const systemRandom: RandomSource;
+/** The most bytes one `random-bytes` may ask for (the kernel's `RANDOM_BYTES_MAX`). */
+declare const RANDOM_BYTES_MAX = 1024;
+/** Standard padded base64 (the wire form of a `Random` answer). */
+declare function base64Standard(bytes: Uint8Array): string;
+/** URL-safe base64 without padding (the `random-bytes` value; the kernel's `codec::base64url_encode`). */
+declare function base64Url(bytes: Uint8Array): string;
+/**
+ * `random-bytes`: the success payload for `bytes` drawn from the host CSPRNG; a bad count or key is the effect's
+ * failure. A keyed call echoes its `key` beside the `value`.
+ */
+declare function randomBytesPayload(ports: Pick<SecretPorts, 'random'>, bytes: RuntimeValue | undefined, key?: RuntimeValue): {
+    value: string;
+    key?: string;
+};
+/** `credential-status`: a bare name selects the viewer; an explicit slot selects its declared scope. */
+declare function credentialStatusPayload(ports: Pick<SecretPorts, 'secrets'>, credential: RuntimeValue | undefined, principal: string | undefined): Promise<CredentialPayload>;
+/** `credential-forget`: drops the signed-in viewer's credential; `{ connected: false }`. */
+declare function credentialForgetPayload(ports: Pick<SecretPorts, 'secrets'>, credential: RuntimeValue | undefined, principal: string | undefined): Promise<{
+    connected: false;
+    label: string;
+}>;
+declare function createSecretPorts(options?: SecretPortsOptions): SecretPorts;
+/** Ports of a browser: it holds no credential, so a secret ask fails and the CSPRNG is the page's. */
+declare function createBrowserSecretPorts(): SecretPorts;
+
+export { RANDOM_BYTES_MAX, base64Standard, base64Url, createBrowserSecretPorts, createCredentialAdminPort, createCredentialConnectPort, createSecretPorts, createSecretStore, credentialForgetPayload, credentialStatusPayload, envTailsOf, randomBytesPayload, systemRandom, userCredentialKey };
+export type { CredentialAdminPort, CredentialConnectPort, EnvTailsPort, RandomSource, SecretPorts, SecretPortsOptions, SecretStore, SecretStoreHost };

package/dist/kernel/secret-ports.js

@@ -0,0 +1,2 @@
+export { RANDOM_BYTES_MAX, base64Standard, base64Url, createBrowserSecretPorts, createCredentialAdminPort, createCredentialConnectPort, createSecretPorts, createSecretStore, credentialForgetPayload, credentialStatusPayload, envTailsOf, randomBytesPayload, systemRandom, userCredentialKey } from '../chunk-ZUSM4VW4.js';
+import '../chunk-HLOUDLPI.js';

package/dist/kernel/wire.d.ts

@@ -0,0 +1,104 @@
+import { KernelEvaluatorExports } from '@almadar/core';
+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;
+    /** 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, 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;
+    /** 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;
+    /** 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;
+    /** The program (as JSON) whose declared credentials this server's credential effects manage beside its own. */
+    setManagedProgram(programJson: string): void;
+    lastError(): string;
+    /** A server holding this one's registered program and none of its session (a stateless request's kernel). */
+    fork(): KernelServerHandle;
+    forkProgram(programJson: string): KernelServerHandle;
+    free(): void;
+}
+/** The `Server` constructor of a kernel module. */
+interface KernelServerClass {
+    /** `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 {
+    Server: KernelServerClass;
+    /** Whether the absolute `glob` matches `path`, as the one-grant matcher `os/glob` filters with. */
+    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. */
+    osStreamOps(): string;
+    /** The `{ event, payload }` JSON a deferred keyed `os/` call's outcome fires on its call site, or `null` when it declares no route. */
+    osCompletionEvent(siteJson: string, key: string, outcomeJson: string): string;
+    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 { FiredByOrbital, KernelModule, KernelServerClass, KernelServerHandle };

package/dist/kernel/wire.js

@@ -0,0 +1 @@
+import '../chunk-EZZYLTWY.js';

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.d.ts

@@ -0,0 +1,12 @@
+import { LazyPage, OrbitalSchema } from '@almadar/core';
+import { SchemaLoader, LoadResult } from './schema-loader.js';
+
+/**
+ * `uses lazy`: the behavior behind a lazy page lives in its own `.orb`, at the
+ * page's `orbRef` relative to the importer's `.orb`, and is loaded when the
+ * page is opened.
+ */
+
+declare function loadLazyPage(loader: SchemaLoader, page: LazyPage, importerPath?: string): Promise<LoadResult<OrbitalSchema>>;
+
+export { loadLazyPage };

package/dist/loader/lazy-page.js

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

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

@@ -0,0 +1,144 @@
+import { OrbitalSchema, Orbital, DeclaredTraitConfig } from '@almadar/core';
+
+/**
+ * SchemaLoader Interface
+ *
+ * Abstract interface for loading OrbitalSchema files from various sources.
+ * Implementations exist for:
+ * - FileSystemLoader (Node.js) - uses fs module
+ * - UnifiedLoader (Auto-detect) - routes to appropriate loader
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result of loading a schema.
+ */
+interface LoadedSchema {
+    /** The loaded schema */
+    schema: OrbitalSchema;
+    /** Source path/URL (resolved) */
+    sourcePath: string;
+    /** Original import path */
+    importPath: string;
+}
+/**
+ * Result of loading a single orbital from a schema.
+ */
+interface LoadedOrbital {
+    /** The loaded orbital — the named one when requested, else the first. */
+    orbital: Orbital;
+    /**
+     * EVERY orbital in the loaded schema. `Alias.traits.X` carries no orbital
+     * segment, so a multi-orbital behavior's traits and pages must all stay
+     * reachable; resolving against `orbital` alone silently loses everything
+     * outside it. Mirrors the compiled path's `AliasEntry.orbitals`.
+     */
+    orbitals?: Orbital[];
+    /**
+     * The loaded schema's own app-level `config`, when it declares one.
+     * Traits from this orbital must resolve against THIS config, not the
+     * consumer's — omitted (never `undefined`) when the schema declares none.
+     */
+    schemaConfig?: DeclaredTraitConfig;
+    /** Source path/URL (resolved) */
+    sourcePath: string;
+    /** Original import path */
+    importPath: string;
+}
+/**
+ * Loader result with error handling.
+ */
+type LoadResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Base options for all loaders.
+ */
+interface BaseLoaderOptions {
+    /** Base path/URL for resolving relative imports */
+    basePath: string;
+    /** Standard library root path/URL */
+    stdLibPath?: string;
+    /** Scoped package roots (e.g., { "@game-lib": "/path/to/lib" }) */
+    scopedPaths?: Record<string, string>;
+}
+/**
+ * Abstract interface for schema loaders.
+ *
+ * All loaders must implement:
+ * - load() - Load a schema from an import path
+ * - resolvePath() - Resolve an import path to absolute path/URL
+ *
+ * @example
+ * ```typescript
+ * // Using FileSystemLoader (Node.js)
+ * const loader: SchemaLoader = new FileSystemLoader({ basePath: "/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");
+ * ```
+ */
+interface SchemaLoader {
+    /**
+     * Load a schema from an import path.
+     *
+     * @param importPath - The import path (e.g., "./health.orb", "std/behaviors/game-core")
+     * @param fromPath - The path of the file doing the import (for relative resolution)
+     * @param chain - Import chain for circular detection (optional)
+     */
+    load(importPath: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedSchema>>;
+    /**
+     * Load a specific orbital from a schema by name.
+     *
+     * @param importPath - The import path
+     * @param orbitalName - The orbital name (optional, defaults to first orbital)
+     * @param fromPath - The path of the file doing the import
+     * @param chain - Import chain for circular detection (optional)
+     */
+    loadOrbital(importPath: string, orbitalName?: string, fromPath?: string, chain?: ImportChainLike): Promise<LoadResult<LoadedOrbital>>;
+    /**
+     * Resolve an import path to an absolute path/URL.
+     *
+     * @param importPath - The import path
+     * @param fromPath - The path of the file doing the import (optional)
+     */
+    resolvePath(importPath: string, fromPath?: string): LoadResult<string>;
+    /**
+     * Clear the loader's cache.
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+    };
+}
+/**
+ * Interface for import chain (circular detection).
+ * This allows different implementations to interoperate.
+ */
+interface ImportChainLike {
+    /**
+     * Try to add a path to the chain.
+     * @returns Error message if circular, null if OK
+     */
+    push(absolutePath: string): string | null;
+    /**
+     * Remove the last path from the chain.
+     */
+    pop(): void;
+    /**
+     * Clone the chain for nested loading.
+     */
+    clone(): ImportChainLike;
+}
+
+export type { BaseLoaderOptions, ImportChainLike, LoadResult, LoadedOrbital, LoadedSchema, SchemaLoader };

package/dist/loader/schema-loader.js

@@ -0,0 +1 @@
+import '../chunk-ELBLT2HZ.js';

package/dist/persistence/native-memory.d.ts

@@ -0,0 +1,28 @@
+import { PersistenceAdapter, KernelMemoryStoreWire, EntityRow, RowQuery, RowQueryPage, RowIdPage, QueryCapabilities, RowWriteOp, RowWriteOutcome, RowWriteBatch, WriteCapabilities } from '@almadar/core';
+
+declare class NativeMemoryWriteError extends Error {
+    readonly outcome: RowWriteOutcome;
+    constructor(outcome: RowWriteOutcome);
+}
+declare class NativeMemoryPersistenceAdapter implements PersistenceAdapter {
+    readonly store: KernelMemoryStoreWire;
+    constructor(store: KernelMemoryStoreWire);
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<EntityRow[]>;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    queryPage(entityType: string, query: RowQuery): Promise<RowQueryPage>;
+    queryIds(entityType: string, query: RowQuery): Promise<RowIdPage>;
+    queryCapabilities(_entityType: string): QueryCapabilities;
+    writeWhere(op: RowWriteOp): Promise<RowWriteOutcome>;
+    writeBatch(batch: RowWriteBatch): Promise<RowWriteOutcome[]>;
+    writeCapabilities(_entityType: string): WriteCapabilities;
+    bindCollection(entityType: string, collection: string): void;
+    clear(): void;
+    snapshot(): Record<string, EntityRow[]>;
+}
+
+export { NativeMemoryPersistenceAdapter, NativeMemoryWriteError };

package/dist/persistence/native-memory.js

@@ -0,0 +1 @@
+export { NativeMemoryPersistenceAdapter, NativeMemoryWriteError } from '../chunk-7SDV3QWR.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

@@ -0,0 +1,59 @@
+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 { 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 '@almadar/core/kernel-wire';
+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
+ * (`openLocalKernel`), and this host answers its I/O. The offline preview and the browser-stored side of a
+ * residence-routed host both use it.
+ */
+
+interface LocalKernelOptions {
+    /** The initialised `@almadar/kernel` module with its language already installed (`loadBrowserKernel`): opening a kernel installs nothing. */
+    kernel: KernelModule;
+    schema: OrbitalSchema;
+    /** Every row the kernel reads and writes (`localStorePersistence` over a browser store). */
+    persistence: PersistenceAdapter;
+    /** Answers every `call-service`; absent, the default provider. */
+    callService?: EffectHandlers['callService'];
+    /** The running app lent to `call-service` providers; absent, a provider reads the rows its viewer may read and dispatches no input. */
+    servicePorts?: KernelHostPorts['servicePorts'];
+    /** Where a follow-on call's outcome is dispatched; absent, nowhere. */
+    deferCallOutcome?: KernelHostPorts['deferCallOutcome'];
+    pageFacts?: KernelHostPorts['pageFacts'];
+    hostActions?: KernelHostPorts['hostActions'];
+    secretPorts?: SecretPorts;
+    onDevice?: OnDeviceModelPorts;
+    tabs?: BrowserTabPort;
+    /** 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;
+/** A kernel over a local store, answering its I/O with `persistence` and the given ports. */
+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 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: 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

@@ -0,0 +1,14 @@
+export { createLocalStoreTransport, localStorePersistence, openLocalKernel, resolveLocalRows } from '../../chunk-MU335ZA4.js';
+import '../../chunk-4SEK5ER2.js';
+import '../../chunk-UBN5JJKZ.js';
+import '../../chunk-O57GKTYU.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-HLOUDLPI.js';
+import '../../chunk-MZKIL5IN.js';
+import '../../chunk-UD2CXYSJ.js';

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

@@ -0,0 +1,15 @@
+import { EventTransport } from '../../client/EventTransport.js';
+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 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;
+
+export { createResidenceTransport };
+export type { ResidenceTransportOptions };

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

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

package/dist/runtime/evaluation/routed-persistence.d.ts

@@ -0,0 +1,9 @@
+import { PersistenceAdapter } from '@almadar/core';
+
+/**
+ * One persistence over two stores: `stored` entities (a program's browser-stored ones) go to `stored`, every other entity to
+ * `other`. The kernel reads and writes every entity through one adapter; a batch is one store's transaction, so it stays in one.
+ */
+declare function routeByEntity(storedEntities: ReadonlySet<string>, stored: PersistenceAdapter, other: PersistenceAdapter): PersistenceAdapter;
+
+export { routeByEntity };