@almadar/shell-runtime 0.0.0-stage → 1.0.0

package/dist/kernel/engine.d.ts

@@ -0,0 +1,195 @@
+import { OrbitalSchema, ExternalInput, InboundRoute, InboundAnswer, InboundDelivery, EventPayload, EventRequest, LiveBroadcastItem, MountSeed, PayloadField, JsonSchema, PayloadIssue, EntityRow, UserContext, RowSetRef, RowQueryPage, EventResponse, EventStreamItem, JsonValue } from '@almadar/core';
+import { ProgramSurface } from '@almadar/core/kernel-wire';
+import { KernelHostPorts, KernelAnswerScope } from './host.js';
+import { KernelModule, KernelServerHandle, FiredByOrbital } from './wire.js';
+import '../effects/in-flight-calls.js';
+import '../service/service-provider.js';
+import './program-effects.js';
+import './secret-ports.js';
+import '../credentials/vault.js';
+import './os-port.js';
+
+/**
+ * The kernel-backed implementation of `evaluateOrbitalEvent` / `OrbitalServerRuntime`: the Rust kernel
+ * (`@almadar/kernel`, WebAssembly) decides every execution step; this host answers the I/O it asks for
+ * and nothing else. The continuation of a stopped dispatch never leaves the wasm instance.
+ */
+
+type ContractAsk = <T>(schema: {
+    parse(input: ReturnType<typeof JSON.parse>): T;
+}, query: object) => T;
+declare function contractAnswers(ask: ContractAsk): {
+    findExternalInput(orbital: string, trait: string, event: string): ExternalInput | undefined;
+    findInbound(name: string): {
+        route: InboundRoute;
+    } | {
+        answer: InboundAnswer;
+    };
+    inboundPayload(route: InboundRoute, delivery: InboundDelivery, credential: string | null | undefined): EventPayload;
+    inboundAnswer(route: InboundRoute, emitted: readonly {
+        event: string;
+        payload?: EventPayload;
+    }[], error: string | undefined): InboundAnswer;
+    credentialUnset(credential: string): InboundAnswer;
+    dispatchFailed(message: string): InboundAnswer;
+};
+/** The declared-contract answers of a host holding no program: the kernel's own answers on an empty kernel. */
+type ProgramlessContract = ReturnType<typeof contractAnswers>;
+declare class KernelEngine {
+    private readonly kernel;
+    private readonly schemaJson;
+    private readonly ports;
+    private readonly entityTypes;
+    private readonly preserveProgramContext;
+    private readonly lazyDir?;
+    private handle;
+    private readonly turns;
+    private tickRelayIntervalMs;
+    private stateful;
+    constructor(kernel: KernelModule, schemaJson: string, ports: KernelHostPorts, entityTypes?: readonly string[], forkedFrom?: KernelServerHandle, providedHandle?: KernelServerHandle, preserveProgramContext?: boolean, lazyDir?: string | undefined);
+    /**
+     * 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 mounted ticks kept. A stateless host serves each request a
+     * fork (EXEC-DIST-5), `ports` answering it.
+     */
+    fork(ports?: KernelHostPorts): KernelEngine;
+    forkProgram(program: OrbitalSchema, ports?: KernelHostPorts): KernelEngine;
+    /** A server over the host's ports. */
+    private openServer;
+    private declare;
+    /** The contract answers for a host with no program registered yet: the kernel's, asked with no program. */
+    static withoutProgram(kernel: KernelModule): ProgramlessContract;
+    static open(kernel: KernelModule, schema: OrbitalSchema, ports: KernelHostPorts, lazyDir?: string): KernelEngine;
+    /** A fresh kernel on the same program: every trait back at its initial state. */
+    reset(): void;
+    private managedProgram;
+    /** The program whose declared credentials this kernel's credential effects manage beside its own (a console's app). */
+    setManagedProgram(program: OrbitalSchema): void;
+    /** `client` mounted `traits` of `orbital`: their mount-scoped ticks fire while any client holds them. A request derives this itself; this is for a mount made outside a request. */
+    mountClient(client: string, orbital: string, traits: readonly string[]): void;
+    unmountClient(client: string, orbital: string, traits: readonly string[]): void;
+    /** `client` is gone: everything it mounted is released. */
+    releaseClient(client: string): void;
+    /** This host holds the circuit state: the kernel takes a client's copy of it only on a delegated leg and refuses any other request carrying one. */
+    setStateful(): void;
+    /** Whether the program declares any tick: the host runs its timer only then. */
+    declaresTicks(): boolean;
+    /** Queue a tick-stamped dispatch for the coalesced peer relay; the ms after which to flush when it opened a window. */
+    relayTick(orbital: string, request: EventRequest): number | undefined;
+    /** The relay window's length in ms; the kernel's default is 50. */
+    setTickRelayInterval(intervalMs: number): void;
+    /** Every item queued since the window opened, in first-arrival order; the window closes. */
+    flushTickRelay(): LiveBroadcastItem[];
+    /** One pass of the kernel's tick clock: the ticks due at monotonic `nowMs` that this server runs (`[background]` ticks, and those of a mounted trait), keyed by the orbital each `runTick` request is addressed to. */
+    tickPass(nowMs: number): FiredByOrbital;
+    /** Stop the kernel's tick clock; its phase is kept. */
+    tickPause(): void;
+    /** Restart the kernel's tick clock; the paused span is never counted. */
+    tickResume(): void;
+    tickPaused(): boolean;
+    /** What this host mounts when it starts: the kernel's boot mounts for the side it serves (EXEC-ENDPOINT-3). */
+    bootMounts(side: 'server' | 'process'): MountSeed[];
+    /** What mounts when a client opens `routePath` (EXEC-ENDPOINT-3). */
+    routeMounts(routePath: string): MountSeed[];
+    dispose(): void;
+    private readonly answers;
+    private contract;
+    /** Every external input the program declares: what an outside client may send which trait. */
+    externalInputs(): ExternalInput[];
+    /** What the kernel holds of every trait of the program, in name order, and the browser-stored entities. */
+    programSurface(): ProgramSurface;
+    /** The entities a provider acting as the caller may read. */
+    readableEntities(): string[];
+    /** The declared input of `trait.event` in `orbital`, when there is one. */
+    findExternalInput(orbital: string, trait: string, event: string): ExternalInput | undefined;
+    /** The declared input a `listens`-addressed event names from `caller`'s position (`EVENT`, `Trait.EVENT`, `Orbital.Trait.EVENT`), when there is one. */
+    findInputByAddress(address: string, caller: {
+        orbital: string;
+        trait: string;
+    }): ExternalInput | undefined;
+    /** A declared payload as the JSON Schema of one object: what a tool-calling model fills. */
+    payloadJsonSchema(fields: readonly PayloadField[]): JsonSchema;
+    /** The ways `value` misses the declared payload `fields`. */
+    payloadIssues(fields: readonly PayloadField[], value: EventPayload): PayloadIssue[];
+    /** The route a hook name is delivered to, or the answer to write for a hook the program does not serve. */
+    findInbound(name: string): {
+        route: InboundRoute;
+    } | {
+        answer: InboundAnswer;
+    };
+    /** The trait that handles `event` as an inbound hook in `orbital`, with the refusal message, when a client-facing request names it. */
+    inboundOnly(orbital: string, trait: string | undefined, event: string): {
+        trait: string;
+        message: string;
+    } | undefined;
+    /** The payload an inbound event is delivered with. */
+    inboundPayload(route: InboundRoute, delivery: InboundDelivery, credential: string | null | undefined): EventPayload;
+    /** The HTTP answer a finished dispatch produced for `route`. */
+    inboundAnswer(route: InboundRoute, emitted: readonly {
+        event: string;
+        payload?: EventPayload;
+    }[], error: string | undefined): InboundAnswer;
+    /** The answer for a route whose credential the host holds no value for. */
+    credentialUnset(credential: string): InboundAnswer;
+    /** The answer for a delivery whose dispatch failed. */
+    dispatchFailed(message: string): InboundAnswer;
+    /** The name of the program's `[identity]` entity, when it declares one. */
+    identityEntity(): string | undefined;
+    /** The orbital that declares `entity` inline. */
+    entityOwnerOrbital(entity: string): string | undefined;
+    /** `rows` of `entity` as `user` reads them: narrowed by the entity's declared `@read`, which the kernel evaluates with `@user` bound to the viewer. */
+    readRows(entity: string, rows: readonly EntityRow[], user: UserContext | undefined): EntityRow[];
+    liveItemDelivered(item: object, clientId?: string): boolean;
+    /** `OsGrants::allows` over the grants of `orbital` in the program this kernel runs (the app level alone with no orbital). */
+    osAllows(requirementJson: string, orbital?: string): boolean;
+    /** Whether `url`'s origin is declared in the program's `egress` (the kernel's rule). */
+    egressAllows(url: string): boolean;
+    /** Place the program's anchored grants and arguments under the host's anchors. */
+    setOsAnchors(anchorsJson: string): string;
+    /** An `os/` call's arguments with its anchored parts resolved under the host's anchors. */
+    osResolveArgs(op: string, argsJson: string): string;
+    tlsComplete(key: string, outcomeJson: string): string;
+    /** A live stream of `client`'s session opened (EXEC-DIST-9); the id closes it. */
+    openSessionStream(client: string): number;
+    /** The live stream `id` dropped: the kernel frees the session once its streams have all dropped and it is quiet. */
+    closeSessionStream(id: number): boolean;
+    /** The current state of a trait instance, `''` when it has none. */
+    stateOf(traitName: string, entityId?: string): string;
+    /**
+     * `reference` resolved for the identity `scope.originClientId`'s session bound (the anonymous viewer with none) against the host-answered store (EXEC-RENDER-3): the rows that still
+     * match its query and that identity'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`.
+     */
+    resolveRows(reference: RowSetRef, scope: KernelAnswerScope): Promise<RowQueryPage>;
+    /**
+     * Run `request` against `orbital`. The kernel orders every start and every resumption (EXEC-CONC-2): while another
+     * dispatch holds the lane it answers `queued` and runs the work itself once the lane frees; this host only answers
+     * what each dispatch asks.
+     */
+    evaluate(orbital: string, request: EventRequest, scope: KernelAnswerScope): Promise<EventResponse>;
+    /** The kernel's answer to a start or resume, once it has run: at once, or when the kernel takes it from its queue. */
+    private ran;
+    private running;
+    /** Run each piece of queued work that can run now, in the kernel's order, handing each to the dispatch it continues. */
+    private runQueued;
+}
+/** What `evaluateOrbitalEvent` needs to run a request on the kernel instead of the JS composition. */
+interface KernelEvaluation {
+    engine: KernelEngine;
+    /** The orbital the request is addressed to. */
+    orbital: string;
+    onStream?: (item: EventStreamItem) => void;
+}
+/**
+ * The request as the kernel takes it: the locale the host resolved, the `_targetTrait` sidecar
+ * promoted to `targetTrait`, and the `_activeTraits` sidecar dropped (the kernel's mounted set is explicit,
+ * not carried per request).
+ */
+declare function kernelRequest(request: EventRequest & {
+    user?: JsonValue;
+}, locale: string | undefined): EventRequest;
+declare function evaluateOnKernel(kernel: KernelEvaluation, request: EventRequest, locale: string | undefined): Promise<EventResponse>;
+
+export { KernelEngine, evaluateOnKernel, kernelRequest };
+export type { KernelEvaluation, ProgramlessContract };

package/dist/kernel/engine.js

@@ -0,0 +1,9 @@
+export { KernelEngine, evaluateOnKernel, kernelRequest } from '../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';

package/dist/kernel/frame-applier.d.ts

@@ -0,0 +1,44 @@
+import { FrameWire, RoutedLeg } from '@almadar/core/kernel-wire';
+import { EventResponse } from '@almadar/core';
+import { ClientKernelOutcome, LocalFoldKernel } from '../client/client-kernel.js';
+import '../client/circuit-store.js';
+import '../client/awaiting.js';
+import '../client/state-book.js';
+import '../client/trait-types.js';
+
+/**
+ * Applies one host frame of the tick clock (`Kernel.frame`'s `FrameWire`) to the view. The in-process
+ * kernel already ran the frame, so it folds locally (`LocalFoldKernel`), never through the server fold:
+ * the aggregate response first (embed.rs: "the host folds `response` before the dispatches"; it is built
+ * from the fired ticks' own outcomes, not from the dispatches, so the two are disjoint), then each tick
+ * dispatch. Every post a dispatch owes (its server legs or stateful leg) and every browser-store leg goes
+ * through the injected `FramePostPort`; the answers settle off the frame (`tickSettled`) so a tick round trip
+ * never delays the next frame.
+ */
+
+/** `frame()`'s JSON; `undefined` (no tick due) decodes to `undefined`. */
+declare function decodeFrame(json: string | undefined): FrameWire | undefined;
+type TickEffects = Pick<EventResponse, 'clientEffectsByTrait'>;
+type FrameDispatch = FrameWire['dispatches'][number];
+/** The host transport's side of a frame: posts what a fired tick owes and folds the answer back through the kernel. */
+interface FramePostPort {
+    /** Posts one dispatch's server legs (or stateful leg); resolves to what the server's fold added. */
+    postDispatch(dispatch: FrameDispatch): Promise<TickEffects>;
+    /** Sends a leg the kernel routed to the browser store; `frameResponse` is the frame's aggregate response. */
+    sendBrowserLeg(leg: RoutedLeg, frameResponse: EventResponse): Promise<TickEffects>;
+}
+interface FrameApplied {
+    fired: FrameWire['fired'];
+    /** How many ticks fired, across every orbital. */
+    firedCount: number;
+    folded: number;
+    browserLegs: number;
+    droppedServerEffects: number;
+    /** The head is the frame's aggregate response, then one outcome per browser leg, then one per dispatch. */
+    outcomes: ClientKernelOutcome[];
+    errors: string[];
+}
+declare function applyFrame(json: string | undefined, kernel: LocalFoldKernel, post: FramePostPort | undefined): Promise<FrameApplied>;
+
+export { applyFrame, decodeFrame };
+export type { FrameApplied, FrameDispatch, FramePostPort, TickEffects };

package/dist/kernel/frame-applier.js

@@ -0,0 +1 @@
+export { applyFrame, decodeFrame } from '../chunk-NTFQ36UN.js';

package/dist/kernel/host.d.ts

@@ -0,0 +1,206 @@
+import { PageFactField, BrowserPageFacts, PersistenceAdapter, ServiceParams, EventPayload, JsonValue, UserContext, ServiceHostPorts, OnDeviceModelPorts, BrowserTabPort, JsonObject, EventStreamItem, HostAskCompletion } from '@almadar/core';
+import { InFlightCalls } from '../effects/in-flight-calls.js';
+import { ServiceCallContext } from '../service/service-provider.js';
+import { ProgramEffectName, ProgramEffectOutcome } from './program-effects.js';
+import { SecretPorts } from './secret-ports.js';
+import { Settled, EventRequest, CallSiteWire, SubstrateFailureWire, IoRequestWire, IoAnswerWire, OsError } from '@almadar/core/kernel-wire';
+import { KernelModule } from './wire.js';
+import { OsHostPort, OsCompletionPort, OsTlsPort, OsCompletionEvent } from './os-port.js';
+import '../credentials/vault.js';
+
+/**
+ * The host half of the kernel path: the I/O the kernel asks for, answered with the runtime's own
+ * adapters. Persistence goes through the `PersistenceAdapter` (`@almadar/db`), `call-service` through the
+ * injected provider (or the mock / integrations default the JS stage uses), substrate operators through
+ * the program host. Nothing here decides an execution step.
+ */
+
+/** `call-service`, as the host answers it: the host's handler, mock mode, or the integrations default. */
+type KernelCallService = (service: string, action: string, params: ServiceParams | undefined, context: ServiceCallContext | undefined) => Promise<EventPayload | null>;
+/** A follow-on step's `call-service` outcome, run later as a dispatch of its own on `traitName`. */
+interface DeferredCallOutcome {
+    orbital: string;
+    traitName: string;
+    event: string;
+    payload: EventPayload | undefined;
+    entityId: string | undefined;
+    originClientId: string | undefined;
+    locale: string | undefined;
+}
+interface SubstrateStreamSource {
+    subscribe(message: (value: JsonValue) => void, ended: () => void): () => void;
+}
+/** The `audio/*` asks: a sound or music key, absent where the op names none (stop every sound, stop the music). */
+type HostAudioAsk = {
+    op: 'audio/play-sound';
+    key: string;
+} | {
+    op: 'audio/stop-sound';
+    key: string | undefined;
+} | {
+    op: 'audio/change-music';
+    key: string | undefined;
+} | {
+    op: 'audio/stop-music';
+};
+/** The one object `auth/sign-in` takes: the method and the credentials it needs. */
+type HostSignInRequest = {
+    method: 'google';
+} | {
+    method: 'email';
+    email: string;
+    password: string;
+} | {
+    method: 'emailLink';
+    email: string;
+    continueUrl: string;
+} | {
+    method: 'emailLink';
+    email: string;
+    link: string;
+} | {
+    method: 'customToken';
+    token: string;
+};
+/** What a sign-in answers: the viewer, or `{ sent: true }` for an email link that was only sent. */
+type HostSignInAnswer = {
+    uid: string;
+    email?: string;
+    displayName?: string;
+} | {
+    sent: true;
+};
+/** The one object `auth/consent` takes: the authorize URL the viewer is sent to. */
+interface HostConsentRequest {
+    authorizeUrl: string;
+}
+/** What a consent answers: the `code` and `state` query params of the final redirect URL, read as they are. */
+interface HostConsentAnswer {
+    code: string;
+    state: string;
+}
+/** Why a host ask failed: the viewer closed it, the provider denied it, the request was malformed, or the host has no such action. */
+type HostAskFailureKind = 'cancelled' | 'denied' | 'invalid' | 'unavailable';
+/** A host action's own failure, carrying the kind the completion reports. */
+declare class HostAskError extends Error {
+    readonly kind: HostAskFailureKind;
+    constructor(kind: HostAskFailureKind, message: string);
+}
+/** What the client host does for the `audio/*`, `auth/sign-out`, `auth/sign-in` and `auth/consent` asks; a host that has none refuses them by name. */
+interface KernelHostActions {
+    audio?: (ask: HostAudioAsk) => void;
+    signOut?: () => void | Promise<void>;
+    signIn?: (request: HostSignInRequest) => Promise<HostSignInAnswer>;
+    consent?: (request: HostConsentRequest) => Promise<HostConsentAnswer>;
+}
+/** A host ask's answer: the payload of its success route, or the error and kind of its failure route. */
+type HostAskOutcome = {
+    ok: JsonObject;
+} | {
+    error: string;
+    kind: HostAskFailureKind;
+};
+/** The event a host's answer dispatches: to `trait` (on `entityId` when the frame is a row), carrying `payload`. */
+interface HostAskReturn {
+    trait: string;
+    entityId?: string;
+    event: string;
+    payload: JsonObject;
+}
+interface KernelHostPorts {
+    hostActions?: KernelHostActions;
+    pageFacts?: (fields: readonly PageFactField[]) => BrowserPageFacts;
+    persistence: PersistenceAdapter;
+    callService: KernelCallService;
+    /** The program host, read per call: a host wires it lazily. */
+    programEffect: () => ((op: ProgramEffectName, args: readonly JsonValue[], context?: Pick<ServiceCallContext, 'principal' | 'role'>) => Promise<ProgramEffectOutcome>) | undefined;
+    inFlightCalls: InFlightCalls;
+    /** The running app lent to one `call-service` provider as the caller. */
+    servicePorts: (caller: {
+        orbital: string;
+        trait: string;
+    }, user: UserContext | undefined, message: (payload: EventPayload) => void, assertReentry?: () => void) => ServiceHostPorts;
+    /** Deliver one live message of a running call (`emit.onMessage`) to the requesting tab only, never in-band. */
+    deliverLive: (site: {
+        orbital: string;
+        trait: string;
+        event: string;
+    }, payload: EventPayload, originClientId: string | undefined) => void;
+    /** Read per call: the sink a follow-on call's outcome runs through, absent when the host cannot deliver it to the tab. */
+    deferCallOutcome: () => ((call: DeferredCallOutcome) => void) | undefined;
+    /** The secret store, CSPRNG and credential administration ports the kernel's secret, random and credential asks use. */
+    secretPorts?: SecretPorts;
+    /** The on-device model and embedder; absent, a `browser/prompt` or `browser/embed` ask fails `unconfigured`. */
+    onDevice?: OnDeviceModelPorts;
+    /** The browser's tabs for the `browser/tab-*` effects; absent, a tab ask fails `unavailable`. */
+    tabs?: BrowserTabPort;
+    /** The `os` effect's host (Node: `createNodeOsHost` from `@almadar/shell-node`); absent, every `os` ask is denied, as the native host does with none. */
+    os?: OsHostPort;
+    /** What the kernel decides about a deferred `os` call (which ops defer, the event an outcome fires); absent, every `os` ask is answered in place. */
+    osCompletions?: OsCompletionPort;
+    /** The kernel's TLS state for sockets it owns (EXEC-HTTP-7); absent, a deferred outcome reaches its route as the host gave it. */
+    osTls?: OsTlsPort;
+    /** The kernel's typed parse of a `program/dispatch` event request; absent, that ask is refused. */
+    parseEventRequest?: EventRequestParser;
+    substrateStream?: (op: string, args: readonly JsonValue[], scope: KernelAnswerScope) => SubstrateStreamSource | undefined;
+    substrateMessage?: (site: CallSiteWire, key: string, value: JsonValue) => OsCompletionEvent | null;
+    substrateCompletion?: (site: CallSiteWire, key: string, op: string, args: readonly JsonValue[], outcome: Settled<JsonValue, SubstrateFailureWire>) => OsCompletionEvent | null;
+    /** The host clock in epoch milliseconds, answering the kernel's `clock` ask; absent, the system clock. */
+    now?: () => number;
+}
+/** What one dispatch brings to its answers. */
+interface KernelAnswerScope {
+    /** The orbital the request is addressed to. */
+    orbital: string;
+    /** The requesting tab. */
+    originClientId?: string;
+    locale?: string;
+    entityId?: string;
+    onStream?: (item: EventStreamItem) => void;
+    assertReentry?: () => void;
+}
+/** The kernel's typed parse of a `program/dispatch` event request: the request, or the reason it is none. */
+type EventRequestParser = (payload: JsonObject, options: JsonObject) => Settled<EventRequest, string>;
+/** The request parser over the kernel module: `EventRequest::from_dispatch`, not copied. */
+declare function kernelEventRequestParser(kernel: Pick<KernelModule, 'parseEventRequest'>): EventRequestParser;
+/** `audio/*` and `auth/sign-out`: one ask each, performed by the host's actions; a host without them refuses by name. */
+declare function performHostAsk(actions: KernelHostActions | undefined, op: string, args: readonly JsonValue[]): Promise<Settled<null, string>>;
+/** The `auth/sign-in` request an ask carries, or why it is refused before the host is asked. */
+declare function parseSignInRequest(args: readonly JsonValue[]): {
+    request: HostSignInRequest;
+} | {
+    error: string;
+};
+/** The `auth/consent` request an ask carries, or why it is refused before the host is asked. */
+declare function parseConsentRequest(args: readonly JsonValue[]): {
+    request: HostConsentRequest;
+} | {
+    error: string;
+};
+/** The `code` and `state` query params of a consent's final redirect URL, read as they are; a redirect without both is a denial. */
+declare function consentFromRedirect(redirectUrl: string): HostConsentAnswer;
+/** The answer of one host ask whose completion the host returns: `auth/sign-in` through the host's sign-in, `auth/consent` through its consent, any other op as it is performed (an empty success). */
+declare function performHostAnswer(actions: KernelHostActions | undefined, op: string, args: readonly JsonValue[]): Promise<HostAskOutcome>;
+/** The event `outcome` fires on the ask's declared route, or undefined when the ask declared none for it (nothing fires). */
+declare function hostAskReturn(completion: HostAskCompletion, outcome: HostAskOutcome): HostAskReturn | undefined;
+/**
+ * A deferred raw `os` outcome that belongs to a TLS operation the kernel parked (EXEC-HTTP-7) is finished in the kernel:
+ * it decrypts or encrypts the raw outcome and, while it needs more raw bytes, asks the host's `os` port for them. Any
+ * other key's outcome is returned as it stands.
+ */
+declare function finishTls(ports: KernelHostPorts, os: OsHostPort, key: string, raw: Settled<JsonValue, OsError>): Promise<Settled<JsonValue, OsError>>;
+/**
+ * The same loop, handing the outcome to `finish` in the calling turn whenever the kernel needs no further raw ask
+ * (nothing parked, or done at once); only a parked operation's follow-up ask makes it wait (EXEC-QUEUE-10/13).
+ */
+declare function completeTls(ports: KernelHostPorts, os: OsHostPort, key: string, raw: Settled<JsonValue, OsError>, finish: (outcome: Settled<JsonValue, OsError>) => void): void;
+declare function writeRows(persistence: PersistenceAdapter, request: Extract<IoRequestWire, {
+    kind: 'writeRows';
+}>): Promise<IoAnswerWire>;
+/** Tell the kernel what the adapter pushes down for each entity type, once, before the first dispatch. */
+declare function declareCapabilities(persistence: PersistenceAdapter, declare: (entityType: string, queryJson: string, writeJson: string) => void, entityTypes: readonly string[]): void;
+/** Answer one request of the kernel; a thrown adapter error becomes the request's declared failure. */
+declare function answerRequest(ports: KernelHostPorts, request: IoRequestWire, scope: KernelAnswerScope): Promise<IoAnswerWire>;
+
+export { HostAskError, answerRequest, completeTls, consentFromRedirect, declareCapabilities, finishTls, hostAskReturn, kernelEventRequestParser, parseConsentRequest, parseSignInRequest, performHostAnswer, performHostAsk, writeRows };
+export type { DeferredCallOutcome, EventRequestParser, HostAskFailureKind, HostAskOutcome, HostAskReturn, HostAudioAsk, HostConsentAnswer, HostConsentRequest, HostSignInAnswer, HostSignInRequest, KernelAnswerScope, KernelCallService, KernelHostActions, KernelHostPorts, SubstrateStreamSource };

package/dist/kernel/host.js

@@ -0,0 +1,6 @@
+export { HostAskError, answerRequest, completeTls, consentFromRedirect, declareCapabilities, finishTls, hostAskReturn, kernelEventRequestParser, parseConsentRequest, parseSignInRequest, performHostAnswer, performHostAsk, writeRows } from '../chunk-7WB6VWRK.js';
+import '../chunk-WGCWJOT2.js';
+import '../chunk-ZUSM4VW4.js';
+import '../chunk-FWA5K7Q2.js';
+import '../chunk-HLOUDLPI.js';
+import '../chunk-MZKIL5IN.js';

package/dist/kernel/lane.d.ts

@@ -0,0 +1,7 @@
+declare class LaneHeldByParkedDispatch extends Error {
+    readonly ticket: number;
+    readonly event: string;
+    constructor(ticket: number, event: string);
+}
+
+export { LaneHeldByParkedDispatch };

package/dist/kernel/lane.js

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

package/dist/kernel/os-fetch-port.d.ts

@@ -0,0 +1,7 @@
+import { OsHostPort } from './os-port.js';
+import '@almadar/core';
+import '@almadar/core/kernel-wire';
+
+declare function createFetchOsHost(performFetch: typeof fetch): OsHostPort;
+
+export { createFetchOsHost };

package/dist/kernel/os-fetch-port.js

@@ -0,0 +1,3 @@
+export { createFetchOsHost } from '../chunk-625EP7W2.js';
+import '../chunk-ZUSM4VW4.js';
+import '../chunk-HLOUDLPI.js';

package/dist/kernel/os-port.d.ts

@@ -0,0 +1,155 @@
+import { JsonValue } from '@almadar/core';
+import { OsOp, Settled, OsError, CallSiteWire } from '@almadar/core/kernel-wire';
+
+/**
+ * The `os` ports of a kernel host, with no Node builtin in sight so the browser bundle can import them.
+ * The Node answerer is `os-node.ts`; the grant check is the Rust `OsGrants` (`allows` below), never TypeScript.
+ */
+
+type OsFsMode = 'read' | 'write' | 'create' | 'remove' | 'meta';
+type OsNetKind = 'tcp' | 'udp' | 'listen';
+type OsStdioKind = 'in' | 'out' | 'err';
+type OsSysKind = 'cpu' | 'memory' | 'disk' | 'network' | 'power-state' | 'identity';
+type OsDesktopKind = 'notify' | 'speak' | 'brightness' | 'volume' | 'power';
+/** One thing an `os/` call needs from the program's grants: the JSON of Rust `OsRequirement`. */
+type OsRequirement = {
+    need: 'fs';
+    path: string;
+    mode: OsFsMode;
+} | {
+    need: 'exec';
+    command: string;
+} | {
+    need: 'net';
+    host: string;
+    port: number;
+    kinds: OsNetKind[];
+} | {
+    need: 'env';
+    name: string;
+} | {
+    need: 'stdio';
+    kind: OsStdioKind;
+} | {
+    need: 'sys';
+    kind: OsSysKind;
+} | {
+    need: 'desktop';
+    kind: OsDesktopKind;
+};
+/** The grant decisions the wasm kernel owns (`OsGrants::allows`, the one-grant glob matcher, `is_public_address`). */
+interface OsGrantPort {
+    /** `OsGrants::allows` over the grants of `orbital` (its own plus the app level); with no orbital, the app level alone. */
+    allows(need: OsRequirement, orbital?: string): boolean;
+    /** Whether the absolute `glob` (`**`, `*`, `?`) matches `path`, as a one-grant `fs_allows` for read. */
+    globMatches(glob: string, path: string): boolean;
+    /** `is_public_address`: the rule an outbound host name must pass. */
+    isPublicAddress(ip: string): boolean;
+    /** Place the program's anchored grants and arguments under the host's anchors (`set_os_anchors_json`); answers what grants nothing. */
+    anchor(anchors: OsAnchors): OsAnchorProblem[];
+    /** An `os/` call's arguments with every anchored part replaced by what it names under the host's anchors (`resolve_anchored_args`). */
+    resolveArgs(op: OsOp, args: JsonValue[]): Settled<JsonValue[], OsError>;
+}
+/** An anchored grant entry that grants nothing under the host's anchors. */
+interface OsAnchorProblem {
+    path: string;
+    message: string;
+}
+/** What a host answers an `os` ask with; `close` drops every handle it holds, as the native `OsHandles::close_all`. */
+interface OsHostPort {
+    /** `orbital` is the orbital whose trait made the ask: its grants (plus the app's) answer it. */
+    answer(op: OsOp, args: JsonValue[], orbital?: string): Promise<Settled<JsonValue, OsError>>;
+    /**
+     * `Completions::run_later`: a keyed ask of a completion-deferring op. A failed check (or a key already pending) is the
+     * in-place `error`; `ok` means the work runs in the background and its outcome reaches `deliver` once, unless
+     * the key is cancelled first. A host with no `defer` answers every ask in place.
+     */
+    defer?(op: OsOp, args: JsonValue[], key: string, deliver: (outcome: Settled<JsonValue, OsError>) => void, orbital?: string): Settled<null, OsError>;
+    /**
+     * A keyed stream (`OsOp::is_stream`, EXEC-QUEUE-12): the host binds and answers once in place, then hands each message
+     * to `message` until it ends; `message` answers `false` when no one takes it any more. A failure after the answer
+     * reaches `fail` once. A host with no `stream` answers every stream ask in place, as unsupported.
+     */
+    stream?(op: OsOp, args: JsonValue[], key: string, message: (value: JsonValue) => boolean, fail: (error: OsError) => void, orbital?: string): Promise<Settled<JsonValue, OsError>>;
+    /** `OsHandles::cancel_completion`: drop the pending completion of `key`, or stop its stream; `false` when none is open. */
+    cancel?(key: string): boolean;
+    close(): void;
+}
+/** The event a deferred `os` call's outcome fires on its call site, as the kernel shapes it. */
+interface OsCompletionEvent {
+    event: string;
+    payload: JsonValue;
+}
+/** What the wasm kernel decides about a deferred `os` call: which ops defer, and the event an outcome fires. */
+interface OsCompletionPort {
+    defers(op: OsOp): boolean;
+    streams(op: OsOp): boolean;
+    event(site: CallSiteWire, key: string, outcome: Settled<JsonValue, OsError>): OsCompletionEvent | null;
+}
+/** The next step of a TLS operation the kernel parked on a deferred raw ask. */
+type OsTlsStep = {
+    ask: {
+        op: OsOp;
+        args: JsonValue[];
+    };
+} | {
+    done: Settled<JsonValue, OsError>;
+};
+/** The kernel's TLS sockets (EXEC-HTTP-7): the host's raw outcome of a deferred ask goes in, the next raw ask or the program's outcome comes out. */
+interface OsTlsPort {
+    /** `null` when `key` parks no TLS operation. */
+    complete(key: string, outcome: Settled<JsonValue, OsError>): OsTlsStep | null;
+}
+/** The server handle's TLS export. */
+interface OsTlsKernel {
+    tlsComplete(key: string, outcomeJson: string): string;
+}
+/** The TLS port over the kernel `Server` handle: every decision is `RuntimeKernel::tls_complete`. */
+declare function kernelOsTls(server: () => OsTlsKernel): OsTlsPort;
+/** The kernel exports the completion port is built from. */
+interface OsCompletionMatchers {
+    osDeferringOps(): string;
+    osStreamOps(): string;
+    osCompletionEvent(siteJson: string, key: string, outcomeJson: string): string;
+}
+/** The completion port over the wasm kernel: `OsOp::defers_completion`, `OsOp::is_stream` and `completion_event`, not copied. */
+declare function kernelOsCompletions(kernel: OsCompletionMatchers): OsCompletionPort;
+/** The kernel pieces a grant port is built from: the `Server` handle holding the program's grants and the module-level matchers. */
+interface OsGrantKernel {
+    osAllows(requirementJson: string, orbital?: string): boolean;
+    setOsAnchors(anchorsJson: string): string;
+    osResolveArgs(op: string, argsJson: string): string;
+}
+interface OsGrantMatchers {
+    osGlobMatches(glob: string, path: string): boolean;
+    isPublicAddress(ip: string): boolean;
+}
+/** The grant port over the wasm kernel: every decision is `OsGrants::allows` and the exports beside it. */
+declare function kernelOsGrants(matchers: OsGrantMatchers, server: () => OsGrantKernel): OsGrantPort;
+/**
+ * Where a host anchors `~/` and `./` paths and grants (the user's home and the directory it started the program in), and
+ * what a grant's declared anchors resolve to: its executable's directory and its boot environment (`orbital-core` `OsAnchors`).
+ */
+interface OsAnchors {
+    readonly home?: string;
+    readonly start?: string;
+    readonly exeDir?: string;
+    readonly exe?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** What a written path names under the host's anchors (`OsAnchors::expand`). */
+type AnchoredPath = {
+    kind: 'plain';
+} | {
+    kind: 'anchored';
+    path: string;
+} | {
+    kind: 'unknown';
+    message: string;
+};
+declare function expandAnchor(anchors: OsAnchors, text: string): AnchoredPath;
+/** The grant port a host checks absolute paths through: an fs need also matches the program's `~/` and `./` grants (`OsGrants::fs_allows_at`). */
+declare function anchoredGrants(grants: OsGrantPort, anchors: OsAnchors): OsGrantPort;
+
+export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants, kernelOsTls };
+export type { AnchoredPath, OsAnchorProblem, OsAnchors, OsCompletionEvent, OsCompletionMatchers, OsCompletionPort, OsDesktopKind, OsFsMode, OsGrantKernel, OsGrantMatchers, OsGrantPort, OsHostPort, OsNetKind, OsRequirement, OsStdioKind, OsSysKind, OsTlsKernel, OsTlsPort, OsTlsStep };

package/dist/kernel/os-port.js

@@ -0,0 +1 @@
+export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants, kernelOsTls } from '../chunk-BOVU4TCQ.js';