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

package/dist/session/execution.d.ts

@@ -0,0 +1,65 @@
+import type { NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { CallableReference } from './reference.js';
+declare const EXECUTION_OUTPUT: unique symbol;
+/**
+ * Immediate value of a durable call: the `K.Execution` it created or recovered. `Output` is the
+ * handler output of the called declaration, carried only by the type.
+ */
+export interface ExecutionRef<Output = unknown> {
+    readonly id: NodeId;
+    readonly [EXECUTION_OUTPUT]?: Output;
+}
+export type ExecutionOutcome<Output = unknown> = {
+    readonly kind: 'completed';
+    readonly value: Output;
+} | {
+    readonly kind: 'failed';
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly family?: string;
+        readonly details?: Value;
+    };
+} | {
+    readonly kind: 'cancelled';
+};
+export type ExecutionState = 'pending' | 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'expired';
+export interface ExecutionStatus<Output = unknown> {
+    readonly id: NodeId;
+    readonly function: NodeId;
+    readonly version: `sha256:${string}`;
+    readonly state: ExecutionState;
+    readonly createdAt: string;
+    readonly outcome?: ExecutionOutcome<Output>;
+}
+type Empty = Readonly<Record<string, never>>;
+type ExecutionLike<Output> = ExecutionRef<Output> | NodeId;
+/**
+ * Typed references to the methods of one Execution, for `session.invoke`:
+ *
+ * ```ts
+ * const run = await session.invoke(remind(invoice), { days: 3 })
+ * const outcome = await session.invoke(execution.result(run), { waitMs: 10_000 })
+ * ```
+ */
+export declare const execution: Readonly<{
+    status: <Output>(target: ExecutionLike<Output>) => CallableReference<Empty, ExecutionStatus<Output>>;
+    /** Outcome once terminal; fails `EXECUTION_PENDING` when `waitMs` elapses first. */
+    result: <Output>(target: ExecutionLike<Output>) => CallableReference<{
+        readonly waitMs?: number;
+    }, ExecutionOutcome<Output>>;
+    /** Cooperative cancellation; `force` kills without compensation (owner Domain only). */
+    cancel: <Output>(target: ExecutionLike<Output>) => CallableReference<{
+        readonly force?: boolean;
+    }, ExecutionStatus<Output>>;
+    /** Resolve a named durable promise once (owner Domain only). */
+    signal: (target: ExecutionLike<unknown>) => CallableReference<{
+        readonly name: string;
+        readonly value: Value;
+    }, Empty>;
+    resume: <Output>(target: ExecutionLike<Output>) => CallableReference<Empty, ExecutionStatus<Output>>;
+    /** Forget the Execution and stop its run (owner Domain only). */
+    delete: (target: ExecutionLike<unknown>) => CallableReference<Empty, Empty>;
+}>;
+export {};

package/dist/session/execution.js

@@ -0,0 +1,34 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { execution as methods } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { kernelReference } from './reference.js';
+const bound = {
+    status: kernelReference(methods.status),
+    result: kernelReference(methods.result),
+    cancel: kernelReference(methods.cancel),
+    signal: kernelReference(methods.signal),
+    resume: kernelReference(methods.resume),
+    delete: kernelReference(methods.delete),
+};
+function receiver(execution) {
+    return Path.id(typeof execution === 'string' ? execution : execution.id);
+}
+/**
+ * Typed references to the methods of one Execution, for `session.invoke`:
+ *
+ * ```ts
+ * const run = await session.invoke(remind(invoice), { days: 3 })
+ * const outcome = await session.invoke(execution.result(run), { waitMs: 10_000 })
+ * ```
+ */
+export const execution = Object.freeze({
+    status: (target) => bound.status(receiver(target)),
+    /** Outcome once terminal; fails `EXECUTION_PENDING` when `waitMs` elapses first. */
+    result: (target) => bound.result(receiver(target)),
+    /** Cooperative cancellation; `force` kills without compensation (owner Domain only). */
+    cancel: (target) => bound.cancel(receiver(target)),
+    /** Resolve a named durable promise once (owner Domain only). */
+    signal: (target) => bound.signal(receiver(target)),
+    resume: (target) => bound.resume(receiver(target)),
+    /** Forget the Execution and stop its run (owner Domain only). */
+    delete: (target) => bound.delete(receiver(target)),
+});

package/dist/session/index.d.ts

@@ -1,8 +1,13 @@
 export type { SessionControlOptions, SessionPolicy } from './context/index.js';
-export type { ReadyInstallation } from '../schema/index.js';
+export type { ContentApi, ContentLocation, ContentUploadOptions, ContentUploadResult, } from './content.js';
+export { bindSession, type BoundClientSession, type BoundSessionControls, type BoundSessionSource, } from './bound.js';
+export { createSessionCredentialProvider, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './credential/index.js';
 export type { SessionSnapshot } from './discovery/index.js';
-export type { Auth, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, } from './routing/index.js';
+export type { SessionExchangeOptions, SessionExchangeRequest } from './exchange/index.js';
+export type { Auth, PersistedRoute, SessionRouteArtifact, SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, SessionRequestOptionsWithBody, } from './routing/index.js';
 export { ClientSession, connect, type ClientSessionOptions, type ConnectOptions, } from './session.js';
-export type { CallableReference, InputOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
+export type { CallableReference, InputOfReference, InputModeOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
+export { reference } from './reference.js';
+export { execution, type ExecutionOutcome, type ExecutionRef, type ExecutionState, type ExecutionStatus, } from './execution.js';
 export type { ResolvedView, ViewCatalog } from './views/index.js';
-//# sourceMappingURL=index.d.ts.map
+export type { DomainBinding } from '../graph/domain/index.js';

package/dist/session/index.js

@@ -1,2 +1,5 @@
+export { bindSession, } from './bound.js';
+export { createSessionCredentialProvider, } from './credential/index.js';
 export { ClientSession, connect, } from './session.js';
-//# sourceMappingURL=index.js.map
+export { reference } from './reference.js';
+export { execution, } from './execution.js';

package/dist/session/reference.d.ts

@@ -1,27 +1,55 @@
 import type { Path as PathValue, PathLike } from '@astrale-os/kernel-core/path';
-import type { Revision } from '@astrale-os/kernel-dsl/v1/schema';
+import type { CallableInputOf, CallableInputModeOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ExecutableMethod } from '@astrale-os/kernel-dsl/v1';
+import type { MethodAddress, Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { MeaningFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
 import { type Key as KeyType } from '@astrale-os/kernel-dsl/v1/addressing';
-import type { Input, Result } from '../client/index.js';
+import type { Binary, Input } from '../client/index.js';
+import type { ExecutionRef } from './execution.js';
 declare const REFERENCE_INPUT: unique symbol;
+declare const REFERENCE_INPUT_MODE: unique symbol;
 declare const REFERENCE_OUTPUT: unique symbol;
-export interface CallableReference<InputValue extends Input = Input, Output = unknown> {
+export interface CallableReference<InputValue = Input, Output = unknown, InputMode extends 'value' | 'binary' = 'value' | 'binary'> {
     readonly origin: KeyType.Origin;
-    readonly revision: Revision;
+    /** @deprecated Informational only; dispatch pins `fingerprint` and revision pinning will be removed. */
+    readonly revision?: Revision;
+    /** Meaning fingerprint of the callable; a generated reference always carries one. */
+    readonly fingerprint?: MeaningFingerprint;
     readonly callable: KeyType.Callable;
     readonly target: PathValue;
-    readonly outputMode: Exclude<Result['kind'], 'redirect'>;
+    readonly outputMode: 'value' | 'stream' | 'binary';
     readonly [REFERENCE_INPUT]?: InputValue;
+    readonly [REFERENCE_INPUT_MODE]?: InputMode;
     readonly [REFERENCE_OUTPUT]?: Output;
 }
-export interface InstanceCallableReference<InputValue extends Input = Input, Output = unknown> {
+export interface InstanceCallableReference<InputValue = Input, Output = unknown> {
     (receiver: PathLike): CallableReference<InputValue, Output>;
     readonly origin: KeyType.Origin;
-    readonly revision: Revision;
+    readonly revision?: Revision;
+    readonly fingerprint?: MeaningFingerprint;
     readonly callable: KeyType.Callable;
-    readonly outputMode: Exclude<Result['kind'], 'redirect'>;
+    readonly outputMode: 'value' | 'stream' | 'binary';
 }
-export type InputOfReference<Reference extends CallableReference> = Reference extends CallableReference<infer InputValue, unknown> ? InputValue : never;
-export type OutputOfReference<Reference extends CallableReference> = Reference extends CallableReference<infer _Input, infer Output> ? Output : never;
-export declare function admitReference(input: CallableReference): CallableReference;
+export type InputOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer InputValue, unknown> ? InputValue : never;
+export type OutputOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer Output> ? Output : never;
+export type InputModeOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer _Output, infer Mode> ? Mode : never;
+type ReferenceInput<Callable> = unknown extends CallableInputOf<Callable> ? Input : CallableInputOf<Callable>;
+type HandlerOutput<Callable> = unknown extends CallableOutputOf<Callable> ? unknown : CallableResultOf<Callable, Binary>;
+type ReferenceOutput<Callable> = Callable extends {
+    readonly execution: {
+        readonly durable: true;
+    };
+} ? ExecutionRef<HandlerOutput<Callable>> : HandlerOutput<Callable>;
+type ExecutableStaticMethod = ExecutableMethod<unknown, unknown, true>;
+type ExecutableInstanceMethod = ExecutableMethod<unknown, unknown, false>;
+/** Project one exact resolved Function or static Method into a typed Client reference. */
+export declare function reference<const Callable extends ResolvedFunction | ExecutableStaticMethod>(domain: Pick<Domain, 'origin' | 'revision'>, callable: Callable): CallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>, CallableInputModeOf<Callable>>;
+/** Project one exact resolved instance Method into a receiver-bound typed Client reference. */
+export declare function reference<const Callable extends ExecutableInstanceMethod>(domain: Pick<Domain, 'origin' | 'revision'>, callable: Callable): InstanceCallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>>;
+/**
+ * Reference a Kernel instance Method by its Core coordinate, without a meaning pin, as the Session
+ * addresses every Kernel syscall. Loading the Session therefore never resolves the Kernel Schema.
+ */
+export declare function kernelReference(method: MethodAddress): InstanceCallableReference<unknown>;
+export declare function admitReference(input: CallableReference<unknown>): CallableReference<unknown>;
+export declare function matchesCallable(target: PathValue, callable: KeyType.Callable): boolean;
 export {};
-//# sourceMappingURL=reference.d.ts.map

package/dist/session/reference.js

@@ -1,44 +1,87 @@
 import { Path } from '@astrale-os/kernel-core/path';
-import { Key, patterns, Ref } from '@astrale-os/kernel-dsl/v1/addressing';
+import { callableAddress, Key, MethodKey, patterns, } from '@astrale-os/kernel-dsl/v1/addressing';
+import { callableFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
+const FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+export function reference(domain, callable) {
+    if (Key.origin(callable.key) !== domain.origin)
+        invalid();
+    if ('owner' in callable && !callable.executable)
+        invalid();
+    const common = Object.freeze({
+        origin: domain.origin,
+        revision: domain.revision,
+        fingerprint: callableFingerprint(callable),
+        callable: callable.key,
+        outputMode: callable.output.mode,
+    });
+    if ('owner' in callable && !callable.static) {
+        const bind = (receiver) => admitReference({
+            ...common,
+            target: Path.instanceMethod(Path.from(receiver), callable.key),
+        });
+        return Object.assign(bind, common);
+    }
+    const target = 'owner' in callable
+        ? Path.staticMethod(Path.project(callable.owner.ref), callable.name)
+        : Path.project(callable.ref);
+    return admitReference({ ...common, target });
+}
+/**
+ * Reference a Kernel instance Method by its Core coordinate, without a meaning pin, as the Session
+ * addresses every Kernel syscall. Loading the Session therefore never resolves the Kernel Schema.
+ */
+export function kernelReference(method) {
+    const callable = MethodKey.of(method.owner, method.name);
+    const common = Object.freeze({
+        origin: Key.origin(callable),
+        callable,
+        outputMode: 'value',
+    });
+    const bind = (receiver) => admitReference({ ...common, target: Path.instanceMethod(Path.from(receiver), callable) });
+    return Object.assign(bind, common);
+}
 export function admitReference(input) {
     if (input === null || typeof input !== 'object')
         invalid();
     if (typeof input.origin !== 'string' ||
         !patterns.origin.test(input.origin) ||
-        typeof input.revision !== 'string' ||
-        !patterns.revision.test(input.revision) ||
+        (input.revision !== undefined &&
+            (typeof input.revision !== 'string' || !patterns.revision.test(input.revision))) ||
         typeof input.callable !== 'string' ||
         !Key.is(input.callable) ||
         Key.origin(input.callable) !== input.origin ||
-        !['value', 'stream', 'binary'].includes(input.outputMode))
+        !['value', 'stream', 'binary'].includes(input.outputMode) ||
+        (input.fingerprint !== undefined &&
+            (typeof input.fingerprint !== 'string' || !FINGERPRINT_PATTERN.test(input.fingerprint))))
         invalid();
     const target = Path.from(input.target);
     if (!matchesCallable(target, input.callable))
         invalid();
     return Object.freeze({
         origin: input.origin,
-        revision: input.revision,
+        ...(input.revision === undefined ? {} : { revision: input.revision }),
+        ...(input.fingerprint === undefined ? {} : { fingerprint: input.fingerprint }),
         callable: input.callable,
         target,
         outputMode: input.outputMode,
     });
 }
-function matchesCallable(target, callable) {
-    const ref = Key.ref(callable);
+export function matchesCallable(target, callable) {
+    const coordinate = callableAddress(callable);
     const { anchor, steps } = target.ast;
     const last = steps.at(-1);
-    if (Ref.isMethod(ref)) {
-        if (last?.kind !== 'method' || last.name !== Ref.child(ref))
+    if (coordinate.kind === 'method') {
+        if (last?.kind !== 'method' || last.name !== coordinate.name)
             return false;
         if (last.dispatch === 'instance')
-            return true;
+            return last.class === Key.of(coordinate.owner);
         const owner = steps.at(-2);
         return (anchor.kind === 'domain' &&
             anchor.origin === Key.origin(callable) &&
             steps.length === 2 &&
             owner?.kind === 'projection' &&
-            owner.projection.kind === Ref.namespace(ref) &&
-            owner.projection.name === Ref.member(ref));
+            owner.projection.kind === 'class' &&
+            owner.projection.name === coordinate.owner.name);
     }
     const projection = steps[0];
     return (anchor.kind === 'domain' &&
@@ -46,9 +89,8 @@ function matchesCallable(target, callable) {
         steps.length === 1 &&
         projection?.kind === 'projection' &&
         projection.projection.kind === 'function' &&
-        projection.projection.name === Ref.member(ref));
+        projection.projection.name === coordinate.name);
 }
 function invalid() {
     throw new TypeError('Callable reference is invalid.');
 }
-//# sourceMappingURL=reference.js.map

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

@@ -9,11 +9,20 @@ export interface SessionAuth {
     /** Default TTL for authenticated Calls whose Auth omits a delegation override. */
     readonly ttlSeconds: number;
     resolve(call: invocation.Call, signal: AbortSignal): Auth | Promise<Auth>;
+    /**
+     * Replace the source credential now, before `resolve` would. A Session asks for it only when a
+     * credential it derives from the current source, such as a Domain exchange, could not cover
+     * `ttlSeconds`: a derived credential never outlives its source.
+     */
+    refresh?(signal: AbortSignal): PromiseLike<unknown> | void;
 }
 export interface EffectiveAuth {
     readonly credential?: string;
     readonly delegate?: invocation.Delegate;
 }
+/** Replace the resolved source authority of one Call before routing partitions and presents it. */
+export interface AuthExchange {
+    resolve(call: invocation.Call, auth: EffectiveAuth, operation: SessionOperation): Promise<EffectiveAuth>;
+}
 export declare function admitSessionAuth(input: SessionAuth | undefined): SessionAuth | undefined;
 export declare function resolveAuth(resolver: SessionAuth | undefined, call: invocation.Call, operation: SessionOperation): Promise<EffectiveAuth>;
-//# sourceMappingURL=auth.d.ts.map

package/dist/session/routing/auth.js

@@ -10,7 +10,14 @@ export function admitSessionAuth(input) {
     if (!Number.isSafeInteger(input.ttlSeconds) || input.ttlSeconds < 1) {
         throw new TypeError('Session auth ttlSeconds must be a positive safe integer.');
     }
-    return Object.freeze({ ttlSeconds: input.ttlSeconds, resolve: input.resolve.bind(input) });
+    if (input.refresh !== undefined && typeof input.refresh !== 'function') {
+        throw new TypeError('Session auth refresh capability is invalid.');
+    }
+    return Object.freeze({
+        ttlSeconds: input.ttlSeconds,
+        resolve: input.resolve.bind(input),
+        ...(input.refresh === undefined ? {} : { refresh: input.refresh.bind(input) }),
+    });
 }
 export async function resolveAuth(resolver, call, operation) {
     if (resolver === undefined)
@@ -37,4 +44,3 @@ export async function resolveAuth(resolver, call, operation) {
         : protocol.acceptDelegate(input.delegate);
     return Object.freeze({ credential, delegate });
 }
-//# sourceMappingURL=auth.js.map

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

@@ -1,21 +1,40 @@
-import type { invocation } from '@astrale-os/kernel-protocol';
+import { invocation } from '@astrale-os/kernel-protocol';
 import type { EffectiveAuth } from './auth.js';
-import type { SchemaExpectation } from './expectation.js';
 export interface LearnedRoute {
     readonly route: invocation.Route;
     readonly credential?: string;
     readonly expiresAt: number;
 }
-/** Confidential, process-local warm routing state owned by exactly one ClientSession. */
+export interface PersistedRoute extends LearnedRoute {
+    /** HMAC over this entry and its exact authority partition. */
+    readonly integrity: string;
+}
+export interface SessionRouteArtifact {
+    readonly version: 1;
+    readonly entries: Readonly<Record<string, PersistedRoute>>;
+}
+/** Caller-owned persistence for confidential route artifacts. */
+export interface SessionRouteStore {
+    read(): unknown;
+    write(artifact: SessionRouteArtifact): void;
+}
+/** Confidential warm routing state owned by exactly one ClientSession. */
 export declare class RouteCache {
     private readonly maximumAgeMs;
     private readonly maximumSize;
     private readonly entries;
-    constructor(maximumAgeMs: number, maximumSize?: number);
-    key(source: string, call: invocation.Call, auth: EffectiveAuth, expected?: SchemaExpectation): Promise<string>;
-    get(key: string, now?: number): LearnedRoute | undefined;
-    learn(key: string, route: invocation.Route, credential: string | undefined, now?: number): LearnedRoute;
+    private readonly keyTokens;
+    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>;
+    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. */
     clear(): void;
+    private invalidate;
+    private reserve;
+    private restore;
+    private restoreInput;
+    private persist;
 }
-//# sourceMappingURL=cache.d.ts.map