@astrale-os/kernel-client 0.5.1 → 0.6.0-beta.10

package/dist/session/routing/dispatch.js

@@ -0,0 +1,137 @@
+import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
+import { acceptCall, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
+import { ClientError, ResponseError } from '../../errors/index.js';
+import { runSessionOperation, sessionTransportOptions, allowEndpoint } from '../context/index.js';
+import { resolveAuth } from './auth.js';
+import { selectEnvelope } from './envelope.js';
+export class SessionDispatcher {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    async dispatch(input, options, operation, expected) {
+        this.state.requireOpen();
+        const call = acceptCall(input);
+        // Authority is resolved before warm lookup so changed credentials or delegation cannot reuse a
+        // carrier minted for a different caller partition.
+        const auth = await resolveAuth(this.state.auth, call, operation);
+        const source = await this.sourceKernel(operation);
+        const cacheKey = await this.state.cache.key(source.issuer, call, auth, expected);
+        const dispatch = Object.freeze({
+            call,
+            auth,
+            source,
+            cacheKey,
+            ...(expected === undefined ? {} : { expected }),
+        });
+        const learned = this.state.cache.get(cacheKey);
+        if (learned !== undefined) {
+            return this.dispatchDestinationWithRecovery(learned, dispatch, options, operation);
+        }
+        const result = await this.dispatchSource(dispatch, undefined, options, operation);
+        return this.followSource(result, dispatch, options, operation);
+    }
+    async dispatchSource(state, routing, options, operation) {
+        this.state.requireOpen();
+        allowEndpoint(this.state.sourceEndpoint, this.state.policy);
+        const client = this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }));
+        return runSessionOperation(operation, () => authenticated(client, state.auth.credential).dispatch(state.call, {
+            ...sessionTransportOptions(operation, options.idempotencyKey),
+            ...(state.auth.delegate === undefined ? {} : { delegate: state.auth.delegate }),
+            ...(routing === undefined ? {} : { routing }),
+            ...(state.expected === undefined ? {} : { schema: { revision: state.expected.revision } }),
+        }));
+    }
+    async followSource(result, state, options, operation) {
+        if (result.kind !== 'redirect')
+            return result;
+        const redirect = result.redirect;
+        if (redirect.route.via.issuer !== state.source.issuer) {
+            throw new ClientError('Redirect issuer differs from the session-pinned source Kernel identity.');
+        }
+        requireExpectedPublication(redirect.route, state.expected);
+        const learned = this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential);
+        return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace);
+    }
+    async dispatchDestinationWithRecovery(learned, state, options, operation, trace) {
+        try {
+            return await this.dispatchDestination(learned, state.call, options, operation, state.expected, trace);
+        }
+        catch (cause) {
+            const stale = isAdmittedStaleRouteError(cause);
+            const miss = isAdmittedMissError(cause);
+            if (isRouteCompatibilityConflict(cause)) {
+                this.state.cache.delete(state.cacheKey);
+                throw cause;
+            }
+            if (!stale && !miss)
+                throw cause;
+            this.state.cache.delete(state.cacheKey);
+            if (!operation.claimRecovery())
+                throw cause;
+            const routing = stale
+                ? Object.freeze({
+                    kind: 'refresh',
+                    stale: learned.route.via.publication.etag,
+                })
+                : undefined;
+            const refreshed = await this.dispatchSource(state, routing, options, operation);
+            return this.followSource(refreshed, state, options, operation);
+        }
+    }
+    async dispatchDestination(learned, call, options, operation, expected, trace) {
+        if (learned.route.via.issuer !== (await this.sourceKernel(operation)).issuer) {
+            throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
+        }
+        requireExpectedPublication(learned.route, expected);
+        const envelope = selectEnvelope(learned.route.endpoint, this.state.envelopeTransport, this.state.websocketAvailable, this.state.pool, this.state.policy);
+        const requestOptions = {
+            ...sessionTransportOptions(operation, options.idempotencyKey),
+            routing: learned.route.via,
+        };
+        const result = await runSessionOperation(operation, () => trace === undefined
+            ? authenticated(envelope.client, learned.credential).dispatch(call, requestOptions)
+            : dispatchTrace(envelope.client, learned.credential, call, requestOptions, trace));
+        if (result.kind === 'redirect') {
+            throw new ClientError('A destination redirect is invalid; only the source Kernel may redirect.');
+        }
+        return result;
+    }
+    async sourceKernel(operation) {
+        const snapshot = await this.state.discovery.snapshot(operation);
+        if (snapshot.kernel !== this.state.kernel) {
+            throw new ClientError('Session discovery returned another Kernel identity.');
+        }
+        return Object.freeze({ issuer: snapshot.publication.identity.issuer });
+    }
+}
+function isRouteCompatibilityConflict(input) {
+    if (!(input instanceof ResponseError))
+        return false;
+    const failure = invocationProtocol.serviceErrorOf({
+        code: input.code,
+        message: input.message,
+        ...(input.data === undefined ? {} : { data: input.data }),
+    });
+    return (failure?.data.code === invocationProtocol.SCHEMA_UPGRADE_REQUIRED ||
+        failure?.data.code === invocationProtocol.SCHEMA_REVISION_MISMATCH ||
+        failure?.data.code === invocationProtocol.SERVICE_TRUST_REQUIRED);
+}
+function requireExpectedPublication(route, expected) {
+    if (expected === undefined)
+        return;
+    const actual = route.via.publication;
+    if (actual.origin !== expected.origin || actual.revision !== expected.revision) {
+        throw new ClientError('Resolved route does not match the expected Schema revision.');
+    }
+}
+export function requireResultKind(expected, result) {
+    if (result.kind === expected)
+        return result;
+    if (result.kind === 'stream')
+        void result.stream.cancel(`Expected ${expected} result.`);
+    throw new ClientError(`Function returned ${result.kind}; ${expected} was required.`);
+}
+function authenticated(client, credential) {
+    return credential === undefined ? client : client.as(credential);
+}

package/dist/session/routing/envelope.d.ts

@@ -0,0 +1,13 @@
+import type { publication } from '@astrale-os/kernel-protocol';
+import type { Client } from '../../client/index.js';
+import type { ClientTarget } from '../../pool/index.js';
+import type { SessionPolicy } from '../context/index.js';
+import type { SessionEnvelopeTransport } from './request.js';
+export interface ClientPoolCapability {
+    clientFor(target: ClientTarget): Client;
+}
+export interface EnvelopeSelection {
+    readonly client: Client;
+    readonly destination: ClientTarget;
+}
+export declare function selectEnvelope(endpoints: publication.InvocationEndpoints, preference: SessionEnvelopeTransport, websocketAvailable: boolean, pool: ClientPoolCapability, policy: Readonly<SessionPolicy>): EnvelopeSelection;

package/dist/session/routing/envelope.js

@@ -0,0 +1,35 @@
+import { ClientError } from '../../errors/index.js';
+import { allowEndpoint } from '../context/index.js';
+export function selectEnvelope(endpoints, preference, websocketAvailable, pool, policy) {
+    let destination;
+    if (preference === 'websocket') {
+        if (endpoints.websocket === undefined) {
+            throw new ClientError('Callable does not advertise a WebSocket endpoint.');
+        }
+        if (!websocketAvailable)
+            throw new ClientError('No WebSocket implementation is available.');
+        allowEndpoint(endpoints.websocket, policy);
+        destination = Object.freeze({ transport: 'websocket', url: endpoints.websocket });
+    }
+    else if (preference === 'auto' && endpoints.websocket !== undefined && websocketAvailable) {
+        allowEndpoint(endpoints.http, policy);
+        allowEndpoint(endpoints.websocket, policy);
+        destination = Object.freeze({
+            transport: 'auto',
+            endpoints: Object.freeze({ http: endpoints.http, websocket: endpoints.websocket }),
+        });
+    }
+    else {
+        allowEndpoint(endpoints.http, policy);
+        destination = Object.freeze({ transport: 'http', url: endpoints.http });
+    }
+    const client = pool.clientFor(destination);
+    if (client === null ||
+        typeof client !== 'object' ||
+        typeof client.dispatch !== 'function' ||
+        typeof client.as !== 'function' ||
+        typeof client.close !== 'function') {
+        throw new TypeError('Session client pool capability returned an invalid Client.');
+    }
+    return Object.freeze({ client, destination });
+}

package/dist/session/routing/expectation.d.ts

@@ -0,0 +1,6 @@
+import type { Key, Revision } from '@astrale-os/kernel-dsl/v1';
+/** Private static-consumer expectation carried only by ClientSession.invoke. */
+export interface SchemaExpectation {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+}

package/dist/session/routing/expectation.js

@@ -0,0 +1 @@
+export {};

package/dist/session/routing/index.d.ts

@@ -0,0 +1,6 @@
+export { admitSessionAuth, resolveAuth, type Auth, type EffectiveAuth, type SessionAuth, } from './auth.js';
+export type { SchemaExpectation } from './expectation.js';
+export { RouteCache, type LearnedRoute } from './cache.js';
+export { requireResultKind, SessionDispatcher, type SessionDispatcherOptions } from './dispatch.js';
+export { type ClientPoolCapability, type EnvelopeSelection } from './envelope.js';
+export { admitEnvelopeTransport, admitRequestOptions, type SessionEnvelopeTransport, type SessionRequestOptions, } from './request.js';

package/dist/session/routing/index.js

@@ -0,0 +1,5 @@
+export { admitSessionAuth, resolveAuth, } from './auth.js';
+export { RouteCache } from './cache.js';
+export { requireResultKind, SessionDispatcher } from './dispatch.js';
+export {} from './envelope.js';
+export { admitEnvelopeTransport, admitRequestOptions, } from './request.js';

package/dist/session/routing/request.d.ts

@@ -0,0 +1,8 @@
+import type * as invocation from '@astrale-os/kernel-protocol/invocation';
+import type { SessionControlOptions } from '../context/index.js';
+export type SessionEnvelopeTransport = 'auto' | 'http' | 'websocket';
+export interface SessionRequestOptions extends SessionControlOptions {
+    readonly idempotencyKey?: invocation.IdempotencyKey;
+}
+export declare function admitRequestOptions(input?: SessionRequestOptions): Readonly<SessionRequestOptions>;
+export declare function admitEnvelopeTransport(input: SessionEnvelopeTransport): SessionEnvelopeTransport;

package/dist/session/routing/request.js

@@ -0,0 +1,25 @@
+import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
+import { admitControlOptions } from '../context/index.js';
+export function admitRequestOptions(input = {}) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Session request options are invalid.');
+    }
+    const control = admitControlOptions(input);
+    const fields = Reflect.ownKeys(input);
+    if (fields.some((field) => !['signal', 'timeoutMs', 'idempotencyKey'].includes(String(field)))) {
+        throw new TypeError('Session request options contain unsupported fields.');
+    }
+    const idempotencyKey = input.idempotencyKey === undefined
+        ? undefined
+        : invocationProtocol.acceptIdempotencyKey(input.idempotencyKey, 'request.idempotencyKey');
+    return Object.freeze({
+        ...control,
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+}
+export function admitEnvelopeTransport(input) {
+    if (input !== 'auto' && input !== 'http' && input !== 'websocket') {
+        throw new TypeError('Session envelope transport is invalid.');
+    }
+    return input;
+}

package/dist/session/session.d.ts

@@ -0,0 +1,67 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { PathLike } from '@astrale-os/kernel-core/path';
+import type { Key } from '@astrale-os/kernel-dsl/v1';
+import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
+import type { Call, Input, Result } from '../client/index.js';
+import type { DomainBinding, GraphApi } from '../graph/index.js';
+import type { ClientFactory, ClientPool as ClientPoolType } from '../pool/index.js';
+import type { ReadyInstallation, SchemaApi } from '../schema/index.js';
+import type { ClientWarning } from '../transport/auto/index.js';
+import type { Fetch } from '../transport/http/index.js';
+import type { WebSocketConstructor } from '../transport/websocket/index.js';
+import type { SessionControlOptions, SessionPolicy } from './context/index.js';
+import type { SessionSnapshot } from './discovery/index.js';
+import type { CallableReference, InputOfReference, OutputOfReference } from './reference.js';
+import type { SessionAuth, SessionEnvelopeTransport, SessionRequestOptions } from './routing/index.js';
+import type { ViewCatalog } from './views/index.js';
+export interface ClientSessionOptions {
+    /** Exact canonical source Kernel identity; its invocation and discovery endpoints are derived. */
+    readonly kernel: string;
+    readonly fetch?: Fetch;
+    readonly client?: ClientFactory;
+    readonly pool?: Pick<ClientPoolType, 'clientFor'>;
+    readonly websocket?: WebSocketConstructor;
+    readonly auth?: SessionAuth;
+    readonly policy: SessionPolicy;
+    readonly envelopeTransport?: SessionEnvelopeTransport;
+    readonly onWarning?: (warning: ClientWarning) => void;
+    readonly maximumPublicationBytes?: number;
+    readonly maximumBundleBytes?: number;
+    readonly maximumResponseBytes?: number;
+    readonly timeoutMs?: number;
+}
+export type ConnectOptions = Omit<ClientSessionOptions, 'kernel' | 'policy'> & {
+    readonly url: string;
+    readonly policy?: SessionPolicy;
+};
+/** Caller-owned discovery and redirect-following conversation with one exact source Kernel. */
+export declare class ClientSession {
+    readonly kernel: IssuerId;
+    readonly schema: SchemaApi;
+    readonly graph: GraphApi;
+    private readonly ownedPool?;
+    private readonly discovery;
+    private readonly dispatcher;
+    private readonly lifecycle;
+    private readonly timeoutMs;
+    private readonly routes;
+    private readonly admitTargetViews;
+    private closed;
+    constructor(options: ClientSessionOptions);
+    /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
+    bind<const DomainValue extends Domain>(domain: DomainValue): DomainBinding<DomainValue>;
+    snapshot(options?: SessionControlOptions): Promise<SessionSnapshot>;
+    viewsFor(target: PathLike, options?: SessionControlOptions): Promise<ViewCatalog>;
+    installation(origin: Key.Origin, options?: SessionControlOptions): Promise<ReadyInstallation>;
+    dispatch(call: Call, options?: SessionRequestOptions): Promise<Result>;
+    call(call: Call, options?: SessionRequestOptions): Promise<Input>;
+    invoke<const Reference extends CallableReference>(reference: Reference, input: InputOfReference<Reference>, options?: SessionRequestOptions): Promise<OutputOfReference<Reference>>;
+    stream(call: Call, options?: SessionRequestOptions): Promise<import("../client/result.js").Stream>;
+    binary(call: Call, options?: SessionRequestOptions): Promise<import("@astrale-os/kernel-core/callable").BinaryResult>;
+    close(): void;
+    private requireOpen;
+    private invokeDomainMethod;
+    private operation;
+}
+/** Open one caller-owned conversation with a Kernel using secure defaults. */
+export declare function connect(options: ConnectOptions): ClientSession;

package/dist/session/session.js

@@ -0,0 +1,257 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { Client } from '../client/index.js';
+import { ClientError, SessionError } from '../errors/index.js';
+import { createDomainBinding } from '../graph/domain/binding.js';
+import { createGraph } from '../graph/index.js';
+import { ClientPool } from '../pool/index.js';
+import { createSchema } from '../schema/index.js';
+import { AutoTransport } from '../transport/auto/index.js';
+import { HttpTransport } from '../transport/http/index.js';
+import { WebSocketTransport } from '../transport/websocket/index.js';
+import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
+import { createSessionDiscovery } from './discovery/index.js';
+import { admitReference } from './reference.js';
+import { admitEnvelopeTransport, admitRequestOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
+import { resolveViewsFor, targetViewCatalog } from './views/index.js';
+const DEFAULT_SESSION_POLICY = Object.freeze({ maximumRouteAgeMs: 60_000 });
+/** Caller-owned discovery and redirect-following conversation with one exact source Kernel. */
+export class ClientSession {
+    kernel;
+    schema;
+    graph;
+    ownedPool;
+    discovery;
+    dispatcher;
+    lifecycle = new AbortController();
+    timeoutMs;
+    routes;
+    admitTargetViews;
+    closed = false;
+    constructor(options) {
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('ClientSession options are invalid.');
+        }
+        const policy = admitPolicy(options.policy);
+        this.admitTargetViews = (input) => targetViewCatalog(input, policy);
+        this.kernel = admitKernel(options.kernel, policy.allowInsecureHttp === true);
+        const sourceEndpoint = kernelInvocationEndpoint(this.kernel);
+        const fetch = options.fetch ?? globalThis.fetch;
+        if (typeof fetch !== 'function')
+            throw new TypeError('ClientSession requires Fetch.');
+        const fetchImpl = options.fetch === undefined ? fetch.bind(globalThis) : fetch;
+        if (options.client !== undefined && options.pool !== undefined) {
+            throw new TypeError('ClientSession accepts either client or pool, not both.');
+        }
+        const maximumPublicationBytes = positive(options.maximumPublicationBytes ?? DEFAULT_MAXIMUM_PUBLICATION_BYTES, 'maximumPublicationBytes');
+        const maximumBundleBytes = positive(options.maximumBundleBytes ?? DEFAULT_MAXIMUM_BUNDLE_BYTES, 'maximumBundleBytes');
+        const maximumResponseBytes = positive(options.maximumResponseBytes ?? DEFAULT_MAXIMUM_RESPONSE_BYTES, 'maximumResponseBytes');
+        const timeoutMs = platformDuration(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 'timeoutMs');
+        this.timeoutMs = timeoutMs;
+        const websocketAvailable = options.client !== undefined ||
+            options.pool !== undefined ||
+            options.websocket !== undefined ||
+            typeof globalThis.WebSocket === 'function';
+        const client = options.client ??
+            defaultClientFactory({
+                fetch: fetchImpl,
+                ...(options.websocket === undefined ? {} : { websocket: options.websocket }),
+                ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
+                maximumResponseBytes,
+                timeoutMs,
+            });
+        let pool;
+        if (options.pool === undefined) {
+            const ownedPool = new ClientPool({ client });
+            this.ownedPool = ownedPool;
+            pool = admitClientPool(ownedPool);
+        }
+        else {
+            pool = admitClientPool(options.pool);
+        }
+        this.discovery = createSessionDiscovery({
+            kernel: this.kernel,
+            fetch: fetchImpl,
+            policy,
+            maximumPublicationBytes,
+            maximumBundleBytes,
+            requireOpen: () => this.requireOpen(),
+            acquisitionOperation: () => this.operation(undefined),
+        });
+        this.routes = new RouteCache(policy.maximumRouteAgeMs);
+        this.dispatcher = new SessionDispatcher({
+            kernel: this.kernel,
+            sourceEndpoint,
+            pool,
+            websocketAvailable,
+            auth: admitSessionAuth(options.auth),
+            cache: this.routes,
+            policy,
+            envelopeTransport: admitEnvelopeTransport(options.envelopeTransport ?? 'http'),
+            discovery: this.discovery,
+            requireOpen: () => this.requireOpen(),
+        });
+        this.schema = createSchema((request, options) => this.dispatch(request, options), {
+            maximumPublicationBytes,
+            maximumBundleBytes,
+        });
+        this.graph = createGraph((call, options) => this.call(call, options));
+    }
+    /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
+    bind(domain) {
+        return createDomainBinding(domain, this.graph, (node, method, input) => this.invokeDomainMethod(domain, node, method, input));
+    }
+    snapshot(options) {
+        return this.discovery.snapshot(this.operation(admitControlOptions(options)));
+    }
+    viewsFor(target, options) {
+        this.requireOpen();
+        return resolveViewsFor(async (call, operation) => requireResultKind('value', await this.dispatcher.dispatch(call, {}, operation)).value, this.admitTargetViews, target, this.operation(admitControlOptions(options)));
+    }
+    async installation(origin, options) {
+        const result = await this.schema.introspect({
+            from: { kind: 'installation', origin },
+            select: {
+                state: true,
+                target: true,
+                source: true,
+                bundle: true,
+                readiness: true,
+                capabilities: true,
+            },
+        }, options);
+        if (result?.state !== 'ready' || result.readiness === null) {
+            throw new ClientError(`Domain ${origin} is not ready on this Kernel.`);
+        }
+        return result;
+    }
+    dispatch(call, options) {
+        const admitted = admitRequestOptions(options);
+        return this.dispatcher.dispatch(call, admitted, this.operation(admitted));
+    }
+    async call(call, options) {
+        const result = await this.dispatch(call, options);
+        return requireResultKind('value', result).value;
+    }
+    async invoke(reference, input, options) {
+        const admittedReference = admitReference(reference);
+        const admittedOptions = admitRequestOptions(options);
+        const expected = Object.freeze({
+            origin: admittedReference.origin,
+            revision: admittedReference.revision,
+        });
+        const result = await this.dispatcher.dispatch({ target: admittedReference.target, input }, admittedOptions, this.operation(admittedOptions), expected);
+        const narrowed = requireResultKind(admittedReference.outputMode, result);
+        return (narrowed.kind === 'value'
+            ? narrowed.value
+            : narrowed.kind === 'stream'
+                ? narrowed.stream
+                : narrowed.value);
+    }
+    async stream(call, options) {
+        const result = await this.dispatch(call, options);
+        return requireResultKind('stream', result).stream;
+    }
+    async binary(call, options) {
+        const result = await this.dispatch(call, options);
+        return requireResultKind('binary', result).value;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lifecycle.abort(new SessionError('ClientSession is closed.', { failure: 'closed' }));
+        this.ownedPool?.close();
+        this.routes.clear();
+        this.discovery.clear();
+    }
+    requireOpen() {
+        if (this.closed)
+            throw new SessionError('ClientSession is closed.', { failure: 'closed' });
+    }
+    invokeDomainMethod(domain, node, method, input) {
+        const diagnostics = method.validateInput(input);
+        if (diagnostics.length > 0)
+            throw new TypeError(`Method ${method.key} input is invalid.`);
+        const owner = domain.closure.find(({ origin }) => origin === method.owner.ref.origin);
+        if (owner === undefined)
+            throw new TypeError(`Method owner ${method.owner.ref.origin} is absent.`);
+        return this.invoke({
+            origin: owner.origin,
+            revision: owner.revision,
+            callable: method.key,
+            target: Path.instanceMethod(Path.id(node.id), method.name),
+            outputMode: method.output.mode,
+        }, input);
+    }
+    operation(options) {
+        this.requireOpen();
+        return createSessionOperation(this.lifecycle.signal, options, this.timeoutMs);
+    }
+}
+/** Open one caller-owned conversation with a Kernel using secure defaults. */
+export function connect(options) {
+    if (options === null || typeof options !== 'object') {
+        throw new TypeError('Connect options are invalid.');
+    }
+    const { url, ...rest } = options;
+    return new ClientSession({
+        ...rest,
+        kernel: url,
+        policy: options.policy ?? DEFAULT_SESSION_POLICY,
+    });
+}
+function admitClientPool(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        typeof input.clientFor !== 'function') {
+        throw new TypeError('Session client pool capability is invalid.');
+    }
+    return Object.freeze({
+        clientFor: (target) => admitPooledClient(input.clientFor.call(input, target)),
+    });
+}
+function admitPooledClient(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        typeof input.dispatch !== 'function' ||
+        typeof input.as !== 'function' ||
+        typeof input.close !== 'function') {
+        throw new TypeError('Session client pool capability returned an invalid Client.');
+    }
+    return input;
+}
+function defaultClientFactory(options) {
+    return (target) => {
+        switch (target.transport) {
+            case 'http':
+                return new Client({
+                    transport: new HttpTransport({
+                        url: target.url,
+                        fetch: options.fetch,
+                        timeoutMs: options.timeoutMs,
+                        maximumResponseBytes: options.maximumResponseBytes,
+                    }),
+                });
+            case 'websocket':
+                return new Client({
+                    transport: new WebSocketTransport({
+                        url: target.url,
+                        timeoutMs: options.timeoutMs,
+                        maximumResponseBytes: options.maximumResponseBytes,
+                        ...(options.websocket === undefined ? {} : { websocket: options.websocket }),
+                    }),
+                });
+            case 'auto':
+                return new Client({
+                    transport: new AutoTransport({
+                        endpoints: target.endpoints,
+                        fetch: options.fetch,
+                        timeoutMs: options.timeoutMs,
+                        maximumResponseBytes: options.maximumResponseBytes,
+                        ...(options.websocket === undefined ? {} : { websocket: options.websocket }),
+                        ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
+                    }),
+                });
+        }
+    };
+}

package/dist/session/session.typecheck.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/session.typecheck.js

@@ -0,0 +1,31 @@
+import { NodeId } from '@astrale-os/kernel-core/graph/node';
+import { Path } from '@astrale-os/kernel-core/path';
+import { defineSchema, method, nodeClass, schema } from '@astrale-os/kernel-dsl/v1';
+import { ClientSession, reference } from './index.js';
+void new ClientSession(options);
+void auth;
+void control;
+void envelope;
+void policy;
+void request;
+void snapshot;
+const dynamicReference = reference(dynamicDomain, dynamicMethod)(Path.id(NodeId('dynamic-node')));
+void session.invoke(dynamicReference, dynamicInput);
+const dynamicInputIsClientInput = true;
+const dynamicOutputIsUnknown = true;
+void dynamicInputIsClientInput;
+void dynamicOutputIsUnknown;
+const abstractMethod = method({
+    auth: 'authenticated',
+    input: { type: 'null' },
+    output: { type: 'null' },
+    inheritance: 'abstract',
+});
+const abstractDomain = schema.resolve(defineSchema('client.reference.typecheck', {
+    classes: {
+        AbstractItem: nodeClass({ abstract: true, methods: { abstractMethod } }),
+    },
+}));
+// @ts-expect-error Abstract Methods are declarations and cannot become Client references.
+reference(abstractDomain, abstractDomain.classes.AbstractItem.methods.abstractMethod);
+void {};

package/dist/session/views/catalog.d.ts

@@ -0,0 +1,15 @@
+import type { Key, bundle } from '@astrale-os/kernel-dsl/v1';
+import type { publication } from '@astrale-os/kernel-protocol';
+import { type ResolvedView } from '@astrale-os/kernel-core/schema/kernel/syscalls/view-resolution';
+export type { ResolvedView } from '@astrale-os/kernel-core/schema/kernel/syscalls/view-resolution';
+import type { SessionPolicy } from '../context/index.js';
+/** One verified View declaration joined with its owning Publication and provenance. */
+/** Immutable canonical-key-ordered inventory of Views resolved under one Session revision. */
+export interface ViewCatalog {
+    readonly entrypoint?: ResolvedView;
+    readonly views: readonly ResolvedView[];
+}
+export declare function rootViewCatalog(publication: publication.Publication, artifact: bundle.Bundle, policy: Readonly<SessionPolicy>): ViewCatalog;
+export declare function catalogFromKeys(root: ViewCatalog, keys: readonly Key.View[]): ViewCatalog;
+/** Re-admit one Runtime-resolved heterogeneous View catalog at the Client trust boundary. */
+export declare function targetViewCatalog(input: unknown, policy: Readonly<SessionPolicy>): ViewCatalog;