@astrale-os/kernel-client 0.6.0-beta.80 → 0.6.0-beta.82

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

@@ -1,4 +1,4 @@
 export { admitControlOptions, type SessionControlOptions } from './control.js';
 export { DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_MAXIMUM_ROUTES, DEFAULT_TIMEOUT_MS, platformDuration, positive, } from './limits.js';
-export { createSessionOperation, runSessionOperation, sessionTransportOptions, type SessionOperation, } from './operation.js';
+export { createSessionOperation, remainingSessionTime, runSessionOperation, sessionTransportOptions, type SessionOperation, } from './operation.js';
 export { admitKernel, admitPolicy, allowEndpoint, kernelInvocationEndpoint, type SessionPolicy, } from './policy.js';

package/dist/session/context/index.js

@@ -1,4 +1,4 @@
 export { admitControlOptions } from './control.js';
 export { DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_MAXIMUM_ROUTES, DEFAULT_TIMEOUT_MS, platformDuration, positive, } from './limits.js';
-export { createSessionOperation, runSessionOperation, sessionTransportOptions, } from './operation.js';
+export { createSessionOperation, remainingSessionTime, runSessionOperation, sessionTransportOptions, } from './operation.js';
 export { admitKernel, admitPolicy, allowEndpoint, kernelInvocationEndpoint, } from './policy.js';

package/dist/session/exchange/options.d.ts

@@ -1,11 +1,16 @@
 import { type IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { SessionControlOptions } from '../context/index.js';
 import type { SessionAuth } from '../routing/index.js';
-/** Present each Domain callable with its declaring Domain's credential instead of the source one. */
+/** Choose how authenticated Calls to remote Domains present the Session's source authority. */
 export interface SessionExchangeOptions {
+    /**
+     * `auto` exchanges through each callable's declaring Domain; `source` keeps the source credential.
+     * Defaults to `auto`, including legacy empty objects and options containing only `ttlSeconds`.
+     */
+    readonly mode?: 'auto' | 'source';
     /**
      * Delegation lifetime requested for each Domain credential. The source credential's remaining
-     * lifetime and the Domain's own ceiling may shorten it.
+     * lifetime and the Domain's own ceiling may shorten it. Applies only in `auto` mode.
      */
     readonly ttlSeconds?: number;
 }
@@ -24,6 +29,6 @@ export interface ExchangeRequest {
  * Admit exchange options against the Session auth they extend. Every Domain credential must still
  * cover the Session delegation, so a request that could never cover it is rejected.
  */
-export declare function admitExchangeOptions(input: SessionExchangeOptions | undefined, auth: SessionAuth | undefined): Readonly<Required<SessionExchangeOptions>> | undefined;
+export declare function admitExchangeOptions(input: SessionExchangeOptions | undefined, auth: SessionAuth | undefined): Readonly<Required<Pick<SessionExchangeOptions, 'ttlSeconds'>>> | undefined;
 /** Admit an explicit exchange: the canonical absolute issuer URL of the named Domain and its lifetime. */
 export declare function admitExchangeRequest(domain: string, input: SessionExchangeRequest | undefined): ExchangeRequest;

package/dist/session/exchange/options.js

@@ -12,13 +12,20 @@ export function admitExchangeOptions(input, auth) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
         throw new TypeError('Session exchange options are invalid.');
     }
-    if (Reflect.ownKeys(input).some((key) => key !== 'ttlSeconds')) {
+    if (Reflect.ownKeys(input).some((key) => key !== 'mode' && key !== 'ttlSeconds')) {
         throw new TypeError('Session exchange options contain unexpected fields.');
     }
+    const mode = input.mode === undefined ? 'auto' : input.mode;
+    if (mode !== 'auto' && mode !== 'source') {
+        throw new TypeError('Session exchange mode is invalid.');
+    }
+    if (mode === 'source')
+        return undefined;
     if (auth === undefined)
         throw new TypeError('Session exchange requires Session auth.');
-    const ttlSeconds = admitTtlSeconds(input.ttlSeconds);
-    if (ttlSeconds * 1_000 <= delegationCoverageMs(auth.ttlSeconds)) {
+    const coverageMs = delegationCoverageMs(auth.ttlSeconds);
+    const ttlSeconds = admitTtlSeconds(input.ttlSeconds ?? Math.max(DEFAULT_EXCHANGE_TTL_SECONDS, Math.floor(coverageMs / 1_000) + 1));
+    if (ttlSeconds * 1_000 <= coverageMs) {
         throw new TypeError('Session exchange ttlSeconds must exceed the Session auth ttlSeconds.');
     }
     return Object.freeze({ ttlSeconds });

package/dist/session/exchange/presentation.d.ts

@@ -15,4 +15,4 @@ export interface SessionExchange extends AuthExchange {
  */
 export declare function createSessionExchange(dependencies: ExchangeDependencies & {
     readonly auth: SessionAuth;
-}, options: Readonly<Required<SessionExchangeOptions>>): SessionExchange;
+}, options: Readonly<Required<Pick<SessionExchangeOptions, 'ttlSeconds'>>>): SessionExchange;

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

@@ -27,7 +27,7 @@ export declare class RouteCache {
     private readonly store?;
     constructor(maximumAgeMs: number, maximumSize?: number, store?: SessionRouteStore);
     key(source: string, call: invocation.Call, auth: EffectiveAuth): Promise<string>;
-    get(key: string, sourceCredential?: string, now?: number): Promise<LearnedRoute | undefined>;
+    get(key: string, sourceCredential?: string, now?: number, operationDeadline?: number): Promise<LearnedRoute | undefined>;
     learn(key: string, route: invocation.Route, credential: string | undefined, sourceCredential?: string, now?: number): Promise<LearnedRoute>;
     delete(key: string): void;
     /** Clear this Session's memory without deleting caller-owned persistent state. */

package/dist/session/routing/cache.js

@@ -19,12 +19,12 @@ export class RouteCache {
         const delegate = auth.delegate === undefined ? 'anonymous' : await digestText(canonicalDelegate(auth.delegate));
         return JSON.stringify([source, call.target, credential, delegate]);
     }
-    async get(key, sourceCredential, now = Date.now()) {
+    async get(key, sourceCredential, now, operationDeadline) {
         const cached = this.entries.get(key);
         if (cached === undefined)
             return undefined;
         const token = this.keyTokens.get(key);
-        if (cached.learned.expiresAt <= now) {
+        if (cached.learned.expiresAt <= (now ?? Date.now())) {
             this.invalidate(key);
             return undefined;
         }
@@ -38,6 +38,17 @@ export class RouteCache {
                 this.invalidate(key);
                 return undefined;
             }
+            // HMAC verification can outlast route age. Check the exact-entry fence before live facts.
+            if (cached.learned.expiresAt <= (now ?? Date.now())) {
+                this.invalidate(key);
+                return undefined;
+            }
+        }
+        if (operationDeadline !== undefined &&
+            cached.credentialRefreshBoundary !== undefined &&
+            cached.credentialRefreshBoundary <= operationDeadline) {
+            // This operation needs a fresh carrier; a shorter concurrent operation may still reuse it.
+            return undefined;
         }
         this.entries.delete(key);
         this.entries.set(key, cached);
@@ -45,6 +56,7 @@ export class RouteCache {
     }
     async learn(key, route, credential, sourceCredential, now = Date.now()) {
         const credentialExpiry = credential === undefined ? undefined : jwtExpiry(credential);
+        const credentialRefreshBoundary = credentialExpiry === undefined ? undefined : refreshBoundary(credentialExpiry);
         const expiresAt = Math.min(now + this.maximumAgeMs, refreshBoundary(credentialExpiry));
         const entry = Object.freeze({
             route,
@@ -79,6 +91,7 @@ export class RouteCache {
         }
         this.entries.set(key, Object.freeze({
             learned: entry,
+            ...(credentialRefreshBoundary === undefined ? {} : { credentialRefreshBoundary }),
             ...(integrity === undefined ? {} : { sealed: entry, integrity }),
         }));
         this.persist();
@@ -210,6 +223,9 @@ function admitStoredEntry(input, now, maximumAgeMs) {
             }),
             sealed,
             integrity: value.integrity,
+            ...(credentialExpiry === undefined
+                ? {}
+                : { credentialRefreshBoundary: refreshBoundary(credentialExpiry) }),
         });
     }
     catch {

package/dist/session/routing/dispatch.js

@@ -2,7 +2,7 @@ import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import * as invocationProtocol from '@astrale-os/kernel-protocol/invocation';
 import { acceptCall, Client, dispatchTrace, isAdmittedMissError, isAdmittedStaleRouteError, } from '../../client/index.js';
 import { ClientError, ResponseError } from '../../errors/index.js';
-import { runSessionOperation, sessionTransportOptions, allowEndpoint } from '../context/index.js';
+import { runSessionOperation, remainingSessionTime, sessionTransportOptions, allowEndpoint, } from '../context/index.js';
 import { resolveAuth } from './auth.js';
 import { selectEnvelope, selectEnvelopeTarget } from './envelope.js';
 export class SessionDispatcher {
@@ -27,14 +27,14 @@ export class SessionDispatcher {
             ? resolved
             : await this.state.exchange.resolve(call, resolved, operation);
         const source = this.state.kernel;
-        const cacheKey = await this.state.cache.key(source, call, auth);
+        const cacheKey = await runSessionOperation(operation, () => this.state.cache.key(source, call, auth));
         const dispatch = Object.freeze({
             call,
             auth,
             source,
             cacheKey,
         });
-        let learned = await this.state.cache.get(cacheKey, auth.credential);
+        let learned = await runSessionOperation(operation, () => this.state.cache.get(cacheKey, auth.credential, undefined, operation.deadline));
         if (learned !== undefined) {
             try {
                 requireCachedRoute(learned, source, call.target, streaming === undefined ? this.state.envelopeTransport : 'http', this.state.websocketAvailable, this.state.policy);
@@ -52,6 +52,7 @@ export class SessionDispatcher {
     }
     async dispatchSource(state, routing, options, operation, streaming) {
         this.state.requireOpen();
+        remainingSessionTime(operation);
         allowEndpoint(this.state.sourceEndpoint, this.state.policy);
         const client = streaming === undefined
             ? this.state.pool.clientFor(Object.freeze({ transport: 'http', url: this.state.sourceEndpoint }))
@@ -77,7 +78,7 @@ export class SessionDispatcher {
             throw new ClientError('Redirect issuer differs from the session-pinned source Kernel identity.');
         }
         requireTargetPublication(redirect.route, state.call.target);
-        const learned = await this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential, state.auth.credential);
+        const learned = await runSessionOperation(operation, () => this.state.cache.learn(state.cacheKey, redirect.route, redirect.credential, state.auth.credential));
         return this.dispatchDestinationWithRecovery(learned, state, options, operation, redirect.trace, streaming);
     }
     async dispatchDestinationWithRecovery(learned, state, options, operation, trace, streaming) {
@@ -107,6 +108,7 @@ export class SessionDispatcher {
         }
     }
     async dispatchDestination(learned, call, options, operation, source, trace, streaming) {
+        remainingSessionTime(operation);
         if (learned.route.via.issuer !== source) {
             throw new ClientError('Learned route issuer differs from the session-pinned source Kernel.');
         }

package/dist/session/session.d.ts

@@ -29,7 +29,9 @@ export interface ClientSessionOptions {
     /**
      * Present each Domain callable with a credential its declaring Domain exchanges for the `auth`
      * caller, so the Domain is the principal and the caller is `auth`. Kernel and local callables keep
-     * the `auth` credential.
+     * the `auth` credential. `connect` defaults to `auto` when `auth` is present; `new ClientSession`
+     * keeps source authority when this option is omitted. `{ mode: 'source' }` keeps it for every Call.
+     * Legacy `{}` and `{ ttlSeconds }` options remain equivalent to `{ mode: 'auto' }`.
      */
     readonly exchange?: SessionExchangeOptions;
     /** Optional caller-owned persistence for bounded confidential route artifacts. */
@@ -91,5 +93,5 @@ export declare class ClientSession {
     private invokeDomainMethod;
     private operation;
 }
-/** Open one caller-owned conversation with a Kernel using secure defaults. */
+/** Open a Kernel conversation with secure defaults and automatic Domain exchange when authenticated. */
 export declare function connect(options: ConnectOptions): ClientSession;

package/dist/session/session.js

@@ -253,16 +253,17 @@ export class ClientSession {
         return createSessionOperation(this.lifecycle.signal, options, this.timeoutMs);
     }
 }
-/** Open one caller-owned conversation with a Kernel using secure defaults. */
+/** Open a Kernel conversation with secure defaults and automatic Domain exchange when authenticated. */
 export function connect(options) {
     if (options === null || typeof options !== 'object') {
         throw new TypeError('Connect options are invalid.');
     }
-    const { url, ...rest } = options;
+    const { url, exchange, ...rest } = options;
     return new ClientSession({
         ...rest,
         kernel: url,
-        policy: options.policy ?? DEFAULT_SESSION_POLICY,
+        exchange: exchange === undefined && rest.auth !== undefined ? { mode: 'auto' } : exchange,
+        policy: rest.policy ?? DEFAULT_SESSION_POLICY,
     });
 }
 function admitClientPool(input) {

package/dist/session/session.typecheck.js

@@ -28,6 +28,15 @@ const credentials = createSessionCredentialProvider({
 // A credential provider is a Session authentication resolver; no adapter stands between them.
 const credentialAuth = credentials;
 void new ClientSession({ ...options, auth: credentialAuth });
+// Automatic exchange remains compatible with the original empty and TTL-only options.
+void new ClientSession({ ...options, auth: credentialAuth, exchange: {} });
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { ttlSeconds: 300 } });
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { mode: 'auto' } });
+void new ClientSession({ ...options, auth: credentialAuth, exchange: { mode: 'source' } });
+// @ts-expect-error Exchange accepts named modes, not a boolean switch.
+void new ClientSession({ ...options, exchange: true });
+// @ts-expect-error Unknown exchange modes are not admitted.
+void new ClientSession({ ...options, exchange: { mode: 'invalid' } });
 // @ts-expect-error A minted credential must carry its own absolute expiry.
 void createSessionCredentialProvider({ ttlSeconds: 60, mint: async () => minted.credential });
 const dynamicReference = reference(dynamicDomain, dynamicMethod)(Path.id(NodeId('dynamic-node')));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.80",
+  "version": "0.6.0-beta.82",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -65,14 +65,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.60",
+    "@astrale-os/kernel-core": "0.9.0-beta.61",
     "@astrale-os/kernel-dsl": "0.2.0-beta.43",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.66",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.67",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.68",
+    "@astrale-os/kernel-server": "0.5.0-beta.69",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",