@almadar/shell-runtime 0.0.0-stage → 0.1.0

package/dist/kernel/host.d.ts

@@ -0,0 +1,95 @@
+import { PageFactField, BrowserPageFacts, PersistenceAdapter, ServiceParams, EventPayload, JsonValue, UserContext, ServiceHostPorts, OnDeviceModelPorts, BrowserTabPort, EventStreamItem } 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 { HttpPorts } from './http.js';
+import { CallSiteWire, Settled, SubstrateFailureWire, IoRequestWire, IoAnswerWire } from '@almadar/core/kernel-wire';
+import { OsHostPort, OsCompletionPort, OsCompletionEvent } from './os-port.js';
+import './beacon.js';
+import '../credentials/store.js';
+import './decode.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;
+    user: UserContext | undefined;
+    locale: string | undefined;
+}
+interface SubstrateStreamSource {
+    subscribe(message: (value: JsonValue) => void, ended: () => void): () => void;
+}
+interface KernelHostPorts {
+    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 `http` effect's ports (kernel builder, secrets, egress); absent, an `http` ask fails as unavailable. */
+    http?: HttpPorts;
+    /** 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;
+    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 viewer the dispatch runs as; a substrate operator is called as them. */
+    user?: UserContext;
+    /** The requesting tab. */
+    originClientId?: string;
+    locale?: string;
+    entityId?: string;
+    /** Runs `work` with the host's event queue released (a service call must not hold the next event). */
+    outsideEventQueue?: <T>(work: () => Promise<T>) => Promise<T>;
+    onStream?: (item: EventStreamItem) => void;
+    assertReentry?: () => 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 { answerRequest, declareCapabilities, writeRows };
+export type { DeferredCallOutcome, KernelAnswerScope, KernelCallService, KernelHostPorts, SubstrateStreamSource };

package/dist/kernel/host.js

@@ -0,0 +1,9 @@
+export { answerRequest, declareCapabilities, writeRows } from '../chunk-NATGCIVM.js';
+import '../chunk-HNOAZWFH.js';
+import '../chunk-YO4LWS3I.js';
+import '../chunk-MZKIL5IN.js';
+import '../chunk-FWA5K7Q2.js';
+import '../chunk-VMOBW7RK.js';
+import '../chunk-RBUMDYFS.js';
+import '../chunk-HLOUDLPI.js';
+import '../chunk-MLKGABMK.js';

package/dist/kernel/http.d.ts

@@ -0,0 +1,302 @@
+import { HttpFailurePayload, JsonValue, HttpStreamEvent, RuntimeValue, CredentialPayload, HttpOAuthFailureCode, HttpOAuthFailureReason, HttpCall } from '@almadar/core';
+export { HttpCall } from '@almadar/core';
+import { BeaconDeliveryPorts } from './beacon.js';
+import { CredentialStore } from '../credentials/store.js';
+export { decodeOAuthAsk } from './decode.js';
+import { IoRequestWire, OAuthAsk, OAuthReply, HttpResponseWire, HttpFailureWire, HttpRequestWire } from '@almadar/core/kernel-wire';
+
+/**
+ * The one TypeScript half of the `http` effect: the host side that moves the bytes the Rust request builder
+ * (`@almadar/kernel`, wasm) produced. Both the kernel host (`host.ts`) and the interpreter (`EffectExecutor`)
+ * call it; nothing here builds a request, frames a stream or shapes a payload — the wasm exports do.
+ */
+
+/**
+ * The pure half of `oauth-authorize` (`@almadar/kernel` `oauthAuthorizePlan` / `oauthAuthorizeBuild` / `oauthFailure`);
+ * a kernel build without them cannot run the effect.
+ */
+interface OAuthAuthorizeKernel {
+    /** Parses the client and options: `{ plan, clientId: { name, scope }, issuer, metadata }`; throws the effect's failure message. */
+    oauthAuthorizePlan(clientJson: string, optionsJson: string): string;
+    /** `{ ok: { authUrl, state, grant } }`, `{ failure: OAuthEffectFailurePayload }` or `{ refused: string }`. */
+    oauthAuthorizeBuild(planJson: string, clientId: string, metadataJson: string, stateBase64: string, verifierBase64: string): string;
+    /** The mock backend's `{ authUrl, state, grant }` from a plan and the drawn state bytes. */
+    oauthAuthorizeMockBuild(planJson: string, stateBase64: string): string;
+    /** The failure payload `{ error, code, reason }` of a closed reason. */
+    oauthFailure(reason: string): string;
+}
+/** The `@almadar/kernel` module-level exports the `http` effect uses; each takes and returns JSON text. */
+interface HttpKernel extends Partial<OAuthAuthorizeKernel> {
+    httpDriverStart(callJson: string, egressJson: string): string;
+    httpDriverResume(driverJson: string, answerJson: string): string;
+    isPublicAddress(ip: string): boolean;
+    /** Frames a chunk of a stream (`{ events, carry }`); each event carries `key`. The call's driver is not needed. */
+    frameStream(framing: StreamFramingWire, key: string | null, chunk: string, carry: string): string;
+    /** The events the unterminated tail in `carry` makes at end of body. */
+    frameStreamFinish(framing: StreamFramingWire, key: string | null, carry: string): string;
+    /** Releases what the kernel holds for a call that ends before its final step (cancelled, aborted, thrown). */
+    httpDriverDrop(driverJson: string): void;
+}
+type StreamFramingWire = Extract<IoRequestWire, {
+    kind: 'httpStream';
+}>['framing'];
+/** How a stream's body is framed, and the key each framed event echoes. */
+interface StreamFrame {
+    framing: StreamFramingWire;
+    key: string | null;
+}
+/**
+ * The host's secret store: a credential NAME in, its value out; `set` keeps a minted value (an OAuth2 token) 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 HttpSecrets {
+    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 (an OAuth connection's tokens): 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>;
+    /** Keep a one-use value (a pending OAuth grant) where every instance of the deployment can take it: the credential store's adapter when it shares one-use values, else the minted tier. */
+    hold?(name: string, value: string, ttlMs: number, principal?: string): Promise<void>;
+    /** Remove and return a held or minted value in one step, the single read of a one-use value. */
+    take?(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;
+/** Where a host name points: its addresses, and whether the name already is one. */
+interface ResolvedHost {
+    literal: boolean;
+    addresses: readonly string[];
+}
+interface PinnedInit {
+    method: string;
+    headers: Array<[string, string]>;
+    body?: Uint8Array<ArrayBuffer>;
+    redirect: 'manual';
+    signal?: AbortSignal;
+}
+/** The part of a fetch response the exchange reads. */
+interface PinnedResponse {
+    status: number;
+    headers: {
+        entries(): IterableIterator<[string, string]>;
+    };
+    body: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel?(): Promise<void>;
+            releaseLock?(): void;
+        };
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** Fetch with the connection pinned to `address`, the one that was checked (no resolve-then-connect race). */
+type PinnedFetch = (url: URL, init: PinnedInit, address: string) => Promise<PinnedResponse>;
+/** 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>;
+}
+interface HttpPorts {
+    kernel: () => Promise<HttpKernel>;
+    /** The host CSPRNG `random-bytes` and the driver's `Random` ask draw from. */
+    random: RandomSource;
+    /** The program's declared `egress` origins. */
+    egress: readonly string[];
+    secrets: HttpSecrets;
+    /** The credential store and mode flag the credential administration effects ask; absent, those asks fail unavailable. */
+    credentials?: CredentialAdminPort;
+    fetch: PinnedFetch;
+    /** Looks a host up for the public-address check; `null` where the host cannot resolve a name (a browser). */
+    resolve: ((host: string) => Promise<ResolvedHost>) | null;
+    /** The host's beacon queue and keepalive fetch; absent, a `browser/beacon` call fails `unavailable`. */
+    beacon?: BeaconDeliveryPorts;
+    /** What an `oauth-client` call and the OAuth effects persist; absent, they fail `store-unavailable`. */
+    oauth?: OAuthPort;
+}
+interface HttpPortsOptions {
+    kernel: () => Promise<HttpKernel>;
+    random?: RandomSource;
+    egress: readonly string[];
+    secrets?: HttpSecrets;
+    /** Defaults to the installed credential store and mode flag. */
+    credentials?: CredentialAdminPort;
+    fetch?: PinnedFetch;
+    resolve?: (host: string) => Promise<ResolvedHost>;
+    /** What `oauth-client` calls and the OAuth effects persist; absent, they fail `store-unavailable`. */
+    oauth?: OAuthPort;
+}
+interface BrowserHttpPortsOptions {
+    kernel: () => Promise<HttpKernel>;
+    /** The program's declared `egress` origins. */
+    egress: readonly string[];
+    /** Defaults to the global `fetch`. */
+    fetch?: (url: string, init: RequestInit) => Promise<PinnedResponse & Response>;
+    /** Defaults to `navigator.sendBeacon` (text/plain Blob) when the page has one, and the global `fetch`. */
+    beacon?: BeaconDeliveryPorts;
+}
+/**
+ * What an OAuth flow asks its host to keep (pending grants, connections, the subject index, discovered metadata,
+ * the clock). `principal` is the dispatch's signed-in user, set by the kernel and never by the program.
+ */
+interface OAuthPort {
+    answer(ask: OAuthAsk, principal: string | undefined): Promise<OAuthReply>;
+}
+/** The loud, coded error for a host that gave the `http` effect no ports. */
+declare class HttpUnavailableError extends Error {
+    readonly code = "HTTP_KERNEL_UNAVAILABLE";
+    constructor(detail: string);
+}
+/** A failed `http` effect: its payload is what the `emit.failure` route carries. */
+declare class HttpEffectFailure extends Error {
+    readonly payload: HttpFailurePayload;
+    constructor(payload: HttpFailurePayload);
+}
+/** Where the secrets' durable credentials live: the store a host installed, and how a name resolves through it. */
+interface HttpSecretsHost {
+    store(): Promise<CredentialStore | null>;
+    resolve(name: string, principal: string | undefined): Promise<string | undefined>;
+}
+/** In-process secrets: minted values with an expiry, then the credential store the host holds (by default the one the host installed). */
+declare function createHttpSecrets(now?: () => number, host?: HttpSecretsHost): HttpSecrets;
+/** 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<HttpPorts, '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<HttpPorts, '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<HttpPorts, 'secrets'>, credential: RuntimeValue | undefined, principal: string | undefined): Promise<{
+    connected: false;
+    label: string;
+}>;
+/** The Node half of the server `http` ports: name resolution and the address-pinned fetch (`@almadar/shell-node` installs it). */
+interface NetPort {
+    resolve: (host: string) => Promise<ResolvedHost>;
+    fetch: PinnedFetch;
+}
+declare function installNetPort(port: NetPort): void;
+declare function createHttpPorts(options: HttpPortsOptions): HttpPorts;
+/**
+ * Ports for a client-site `http` (a call with no `auth`): the same kernel driver and exchange as the server,
+ * over the browser's `fetch`. A browser cannot resolve a name or pin a connection, so there is no
+ * public-address check; the program's `egress` (the driver refuses any other origin) and the browser's own
+ * CORS rules bound what the call reaches.
+ */
+declare function createBrowserHttpPorts(options: BrowserHttpPortsOptions): HttpPorts;
+/** What one exchange came to; a cancelled exchange is the caller's abort signal, never an outcome. */
+type Exchange = {
+    kind: 'reply';
+    response: HttpResponseWire;
+} | {
+    kind: 'failure';
+    failure: HttpFailureWire;
+};
+/** Send one built request after its requested retry delay and read the whole reply. */
+declare function sendHttp(ports: HttpPorts, request: HttpRequestWire, signal?: AbortSignal, delayMs?: number): Promise<Exchange>;
+/**
+ * Send one built request and hand each framed event of the body to `onEvent` as it arrives; the reply that
+ * ends the exchange carries an empty body. Framing, and the `key` each event echoes, are the kernel's
+ * (`frameStream`, `frameStreamFinish`) over the ask's `framing` and `key`.
+ */
+declare function streamHttp(ports: HttpPorts, request: HttpRequestWire, stream: StreamFrame, onEvent: (event: HttpStreamEvent) => void, signal?: AbortSignal): Promise<Exchange>;
+/** How a host took one beacon, as the driver's `beacon` answer carries it; a fetch that threw is a failure. */
+type BeaconSettled = {
+    ok: {
+        via: 'queue';
+    } | {
+        via: 'fetch';
+        status: number;
+    } | {
+        via: 'unavailable';
+        message: string;
+    };
+} | {
+    error: {
+        kind: 'failed';
+        message: string;
+    };
+};
+/**
+ * Hand one built beacon request to the host's beacon port. Cancelling stops the wait only: the queue and the
+ * fetch the browser already has are never aborted, and a late completion is dropped.
+ */
+declare function sendBeaconRequest(ports: HttpPorts, request: HttpRequestWire, signal?: AbortSignal): Promise<BeaconSettled>;
+
+type HttpOutcome = {
+    ok: JsonValue;
+} | {
+    error: HttpFailurePayload;
+};
+interface HttpRunOptions {
+    signal?: AbortSignal;
+    /** The dispatch's signed-in user id: whose credential a `scope: "user"` ask names (never set by the program). */
+    principal?: string | undefined;
+    /** Receives each framed event of a `stream` call. */
+    onMessage?: (event: HttpStreamEvent) => void;
+}
+
+declare function isOAuthCode(value: JsonValue | undefined): value is HttpOAuthFailureCode;
+declare function isOAuthReason(value: JsonValue | undefined): value is HttpOAuthFailureReason;
+/** The failure of a call whose host has no port for what it needs. */
+declare function unavailableFailure(error: string, key: string | null): HttpFailurePayload;
+/** The reply the port answered, checked to be one of the closed reply variants. */
+declare function checkOAuthReply(reply: OAuthReply): OAuthReply;
+/**
+ * One `http` effect, driven by the kernel's step machine (`httpDriverStart`/`httpDriverResume`): every ask
+ * (credential, token store, request, stream) is answered here and nothing else is decided in TypeScript.
+ */
+declare function runHttpCall(ports: HttpPorts, call: HttpCall, options?: HttpRunOptions): Promise<HttpOutcome>;
+
+export { HttpEffectFailure, HttpUnavailableError, RANDOM_BYTES_MAX, base64Standard, base64Url, checkOAuthReply, createBrowserHttpPorts, createCredentialAdminPort, createHttpPorts, createHttpSecrets, credentialForgetPayload, credentialStatusPayload, installNetPort, isOAuthCode, isOAuthReason, randomBytesPayload, runHttpCall, sendBeaconRequest, sendHttp, streamHttp, systemRandom, unavailableFailure, userCredentialKey };
+export type { BeaconSettled, BrowserHttpPortsOptions, CredentialAdminPort, Exchange, HttpKernel, HttpOutcome, HttpPorts, HttpPortsOptions, HttpRunOptions, HttpSecrets, HttpSecretsHost, NetPort, OAuthAuthorizeKernel, OAuthPort, PinnedFetch, PinnedInit, PinnedResponse, RandomSource, ResolvedHost, StreamFrame, StreamFramingWire };

package/dist/kernel/http.js

@@ -0,0 +1,6 @@
+export { HttpEffectFailure, HttpUnavailableError, RANDOM_BYTES_MAX, base64Standard, base64Url, checkOAuthReply, createBrowserHttpPorts, createCredentialAdminPort, createHttpPorts, createHttpSecrets, credentialForgetPayload, credentialStatusPayload, installNetPort, isOAuthCode, isOAuthReason, randomBytesPayload, runHttpCall, sendBeaconRequest, sendHttp, streamHttp, systemRandom, unavailableFailure, userCredentialKey } from '../chunk-YO4LWS3I.js';
+import '../chunk-MZKIL5IN.js';
+import '../chunk-VMOBW7RK.js';
+export { decodeOAuthAsk } from '../chunk-RBUMDYFS.js';
+import '../chunk-HLOUDLPI.js';
+import '../chunk-MLKGABMK.js';

package/dist/kernel/lane.d.ts

@@ -0,0 +1,28 @@
+interface LaneTurn {
+    readonly ticket: number;
+}
+declare class LaneHeldByParkedDispatch extends Error {
+    readonly ticket: number;
+    readonly event: string;
+    constructor(ticket: number, event: string);
+}
+interface LaneGuard {
+    readonly turn: LaneTurn;
+    park(event: string): void;
+    resume(): void;
+    release(): void;
+}
+declare class DispatchLane {
+    private nextTicket;
+    private holder;
+    private depth;
+    private parkedEvent;
+    private readonly waiters;
+    assertCanReenter(turn: LaneTurn): void;
+    enter(turn?: LaneTurn): Promise<LaneGuard>;
+    private take;
+    private guard;
+}
+
+export { DispatchLane, LaneHeldByParkedDispatch };
+export type { LaneGuard, LaneTurn };

package/dist/kernel/lane.js

@@ -0,0 +1,2 @@
+export { DispatchLane, LaneHeldByParkedDispatch } from '../chunk-53IPZXDP.js';
+import '../chunk-MLKGABMK.js';

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

@@ -0,0 +1,25 @@
+import { OAuthEffectFailurePayload, RuntimeValue, OAuthAuthorizePayload, OAuthConnectionPayload } from '@almadar/core';
+import { HttpPorts } from './http.js';
+import './beacon.js';
+import '../credentials/store.js';
+import './decode.js';
+import '@almadar/core/kernel-wire';
+
+/**
+ * The interpreter and kernel-host half of the OAuth effects (`oauth-authorize`, `oauth-connection-status`,
+ * `oauth-connection-forget`): the asks that orbital-core's `run_oauth_authorize` / `run_oauth_connection` make,
+ * in the same order, answered here. Every rule (client and option parsing, the authorization URL, the failure
+ * messages) is the kernel's, reached through `@almadar/kernel`; only the sequencing of host asks lives here.
+ */
+
+/** A failed OAuth effect: its payload is what the `emit.failure` route carries. */
+declare class OAuthEffectFailure extends Error {
+    readonly payload: OAuthEffectFailurePayload;
+    constructor(payload: OAuthEffectFailurePayload);
+}
+/** `oauth-authorize`: the kernel's steps, in order — secret, metadata, two draws, pending grant. */
+declare function oauthAuthorizePayload(ports: HttpPorts, client: RuntimeValue | undefined, options: RuntimeValue | undefined, principal: string | undefined, key?: RuntimeValue): Promise<OAuthAuthorizePayload>;
+/** `oauth-connection-status` / `oauth-connection-forget`: store first, then caller (the legacy order). */
+declare function oauthConnectionPayload(ports: HttpPorts, head: 'oauth-connection-status' | 'oauth-connection-forget', provider: RuntimeValue | undefined, principal: string | undefined): Promise<OAuthConnectionPayload>;
+
+export { OAuthEffectFailure, oauthAuthorizePayload, oauthConnectionPayload };

package/dist/kernel/oauth-effects.js

@@ -0,0 +1,7 @@
+export { OAuthEffectFailure, oauthAuthorizePayload, oauthConnectionPayload } from '../chunk-ZAQSS47X.js';
+import '../chunk-YO4LWS3I.js';
+import '../chunk-MZKIL5IN.js';
+import '../chunk-VMOBW7RK.js';
+import '../chunk-RBUMDYFS.js';
+import '../chunk-HLOUDLPI.js';
+import '../chunk-MLKGABMK.js';

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

@@ -0,0 +1,31 @@
+import { HttpSecrets, OAuthPort } from './http.js';
+import '@almadar/core';
+import './beacon.js';
+import '../credentials/store.js';
+import './decode.js';
+import '@almadar/core/kernel-wire';
+
+/** What the person's consent page is opened with. */
+interface OAuthConsentRequest {
+    authUrl: string;
+    state: string;
+    redirectUri: string;
+}
+interface OAuthPortOptions {
+    /** The host's credentials (read per ask when a function: a host installs them at boot). */
+    secrets: HttpSecrets | (() => HttpSecrets);
+    /** The host clock in epoch milliseconds. */
+    now?: () => number;
+    /** Opens the consent page for the person and answers the authorization code it returned, `null` when they declined; absent, the host asks no one. */
+    consent?: (request: OAuthConsentRequest) => Promise<string | null>;
+}
+/**
+ * The port's clock decides expiry (`expiresAt >= now` is live, the inclusive boundary of the native store); the
+ * credential only garbage-collects, so it is given a grace beyond the TTL and an expired state answers `expired`,
+ * not `missing`.
+ */
+declare const PENDING_GRACE_MS: number;
+declare function createOAuthPort(options: OAuthPortOptions): OAuthPort;
+
+export { PENDING_GRACE_MS, createOAuthPort };
+export type { OAuthConsentRequest, OAuthPortOptions };

package/dist/kernel/oauth-port.js

@@ -0,0 +1,2 @@
+export { PENDING_GRACE_MS, createOAuthPort } from '../chunk-4ZICQ5PM.js';
+import '../chunk-MLKGABMK.js';

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

@@ -0,0 +1,133 @@
+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 every registered program declares. */
+    allows(need: OsRequirement): 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 {
+    answer(op: OsOp, args: JsonValue[]): 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): 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): 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 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): 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 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 };
+export type { AnchoredPath, OsAnchorProblem, OsAnchors, OsCompletionEvent, OsCompletionMatchers, OsCompletionPort, OsDesktopKind, OsFsMode, OsGrantKernel, OsGrantMatchers, OsGrantPort, OsHostPort, OsNetKind, OsRequirement, OsStdioKind, OsSysKind };

package/dist/kernel/os-port.js

@@ -0,0 +1,2 @@
+export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants } from '../chunk-REPX5QPI.js';
+import '../chunk-MLKGABMK.js';