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

package/dist/pool/pool.d.ts

@@ -1,63 +1,23 @@
-import type { KernelClient } from '../client/client.js';
-import type { FnMap } from '../client/fn-map.js';
-/**
- * Factory for constructing a `KernelClient` bound to a given URL.
- *
- * The ClientSession's default factory wires `fetch`, `codec`, `requestTimeout`,
- * `defaultTransport`, `defaultProtocol`, `schema`, `hooks`, `retry` from a single
- * base config. Consumers who need custom wire-layer config replace the
- * factory — it is the one wiring seam between ClientSession's config and the
- * client's.
- */
-export type ClientFactory<M extends FnMap = FnMap> = (url: string) => KernelClient<M>;
-/**
- * `ClientPool` configuration. Spec §9.1.
- */
-export type ClientPoolConfig<M extends FnMap = FnMap> = {
-    /** How to build a `KernelClient` for a URL the pool hasn't seen. */
-    clientFactory: ClientFactory<M>;
-    /**
-     * Maximum cached clients. Least-recently-used is evicted when
-     * exceeded. Default: `32`.
-     */
-    maxSize?: number;
-};
-/**
- * URL → `KernelClient` map with bounded LRU eviction. Spec §9.1.
- *
- * Invariants:
- * - Idempotent `disconnect()` — subsequent calls are no-ops.
- * - Post-disconnect `clientFor` throws `PoolClosedError`.
- * - Eviction cascades `disconnect()` to the evicted client.
- * - Calls to `clientFor(url)` return the same instance for the same
- *   URL (until eviction), so pooled-client hook registration is stable.
- */
-export declare class ClientPool<M extends FnMap = FnMap> {
-    private readonly entries;
-    private readonly factory;
-    private readonly maxSize;
+import type { Client } from '../client/index.js';
+import type { ClientTarget } from './target.js';
+export type ClientFactory = (target: ClientTarget) => Client;
+export interface ClientPoolOptions {
+    readonly client: ClientFactory;
+    /** Maximum retained endpoint/transport Clients. Default: 32. */
+    readonly maximumSize?: number;
+}
+/** Bounded LRU pool for shareable one-hop Clients; eviction closes the selected Client. */
+export declare class ClientPool {
+    private readonly clients;
+    private readonly createClient;
+    private readonly maximumSize;
     private closed;
-    private clock;
-    constructor(config: ClientPoolConfig<M>);
-    /**
-     * Resolve or create a client for `url`. Throws `PoolClosedError` if
-     * the pool has been disconnected.
-     */
-    clientFor(url: string): KernelClient<M>;
-    /**
-     * Evict a specific URL and call its client's `disconnect()`.
-     * Idempotent — no-op for unknown URLs.
-     */
-    evict(url: string): void;
-    /**
-     * Tear down every cached client. Idempotent. After disconnect,
-     * `clientFor` throws `PoolClosedError`.
-     */
-    disconnect(): void;
-    /** Current number of cached clients — pool introspection helper. */
+    constructor(options: ClientPoolOptions);
+    clientFor(target: ClientTarget): Client;
+    evict(target: ClientTarget): void;
+    close(): void;
     get size(): number;
-    /** Whether `disconnect()` has been called. */
     get isClosed(): boolean;
-    private evictLeastRecentlyUsed;
+    private evictOldest;
+    private requireOpen;
 }
-//# sourceMappingURL=pool.d.ts.map

package/dist/pool/pool.js

@@ -1,87 +1,69 @@
-import { PoolClosedError } from './errors.js';
-/**
- * URL → `KernelClient` map with bounded LRU eviction. Spec §9.1.
- *
- * Invariants:
- * - Idempotent `disconnect()` — subsequent calls are no-ops.
- * - Post-disconnect `clientFor` throws `PoolClosedError`.
- * - Eviction cascades `disconnect()` to the evicted client.
- * - Calls to `clientFor(url)` return the same instance for the same
- *   URL (until eviction), so pooled-client hook registration is stable.
- */
+import { ClientError } from '../errors/index.js';
+import { admitTarget, targetKey } from './target.js';
+/** Bounded LRU pool for shareable one-hop Clients; eviction closes the selected Client. */
 export class ClientPool {
-    entries = new Map();
-    factory;
-    maxSize;
+    clients = new Map();
+    createClient;
+    maximumSize;
     closed = false;
-    clock = 0;
-    constructor(config) {
-        this.factory = config.clientFactory;
-        this.maxSize = config.maxSize ?? 32;
-        if (this.maxSize < 1) {
-            throw new Error(`ClientPool.maxSize must be >= 1 (got ${this.maxSize})`);
+    constructor(options) {
+        if (typeof options?.client !== 'function') {
+            throw new TypeError('ClientPool client factory is invalid.');
+        }
+        this.createClient = options.client;
+        this.maximumSize = options.maximumSize ?? 32;
+        if (!Number.isSafeInteger(this.maximumSize) || this.maximumSize < 1) {
+            throw new TypeError('ClientPool maximumSize must be a positive safe integer.');
         }
     }
-    /**
-     * Resolve or create a client for `url`. Throws `PoolClosedError` if
-     * the pool has been disconnected.
-     */
-    clientFor(url) {
-        if (this.closed)
-            throw new PoolClosedError();
-        const existing = this.entries.get(url);
+    clientFor(target) {
+        this.requireOpen();
+        const admitted = admitTarget(target);
+        const key = targetKey(admitted);
+        const existing = this.clients.get(key);
         if (existing) {
-            existing.lastUsed = ++this.clock;
+            this.clients.delete(key);
+            this.clients.set(key, existing);
             return existing.client;
         }
-        if (this.entries.size >= this.maxSize)
-            this.evictLeastRecentlyUsed();
-        const client = this.factory(url);
-        this.entries.set(url, { client, lastUsed: ++this.clock });
+        if (this.clients.size === this.maximumSize)
+            this.evictOldest();
+        const client = this.createClient(admitted);
+        this.clients.set(key, { target: admitted, client });
         return client;
     }
-    /**
-     * Evict a specific URL and call its client's `disconnect()`.
-     * Idempotent — no-op for unknown URLs.
-     */
-    evict(url) {
-        const entry = this.entries.get(url);
+    evict(target) {
+        const admitted = admitTarget(target);
+        const key = targetKey(admitted);
+        const entry = this.clients.get(key);
         if (!entry)
             return;
-        this.entries.delete(url);
-        entry.client.disconnect();
+        this.clients.delete(key);
+        entry.client.close();
     }
-    /**
-     * Tear down every cached client. Idempotent. After disconnect,
-     * `clientFor` throws `PoolClosedError`.
-     */
-    disconnect() {
+    close() {
         if (this.closed)
             return;
         this.closed = true;
-        for (const { client } of this.entries.values())
-            client.disconnect();
-        this.entries.clear();
+        for (const { client } of this.clients.values())
+            client.close();
+        this.clients.clear();
     }
-    /** Current number of cached clients — pool introspection helper. */
     get size() {
-        return this.entries.size;
+        return this.clients.size;
     }
-    /** Whether `disconnect()` has been called. */
     get isClosed() {
         return this.closed;
     }
-    evictLeastRecentlyUsed() {
-        let oldestUrl;
-        let oldestTs = Number.POSITIVE_INFINITY;
-        for (const [url, entry] of this.entries) {
-            if (entry.lastUsed < oldestTs) {
-                oldestTs = entry.lastUsed;
-                oldestUrl = url;
-            }
-        }
-        if (oldestUrl !== undefined)
-            this.evict(oldestUrl);
+    evictOldest() {
+        const oldest = this.clients.entries().next().value;
+        if (!oldest)
+            return;
+        this.clients.delete(oldest[0]);
+        oldest[1].client.close();
+    }
+    requireOpen() {
+        if (this.closed)
+            throw new ClientError('ClientPool is closed.');
     }
 }
-//# sourceMappingURL=pool.js.map

package/dist/pool/target.d.ts

@@ -0,0 +1,15 @@
+export type ClientTarget = {
+    readonly transport: 'http';
+    readonly url: string;
+} | {
+    readonly transport: 'websocket';
+    readonly url: string;
+} | {
+    readonly transport: 'auto';
+    readonly endpoints: {
+        readonly http: string;
+        readonly websocket: string;
+    };
+};
+export declare function admitTarget(input: ClientTarget): ClientTarget;
+export declare function targetKey(target: ClientTarget): string;

package/dist/pool/target.js

@@ -0,0 +1,49 @@
+export function admitTarget(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new TypeError('Client target must be an object.');
+    }
+    if (input.transport === 'http') {
+        return Object.freeze({ transport: 'http', url: endpoint(input.url, ['http:', 'https:']) });
+    }
+    if (input.transport === 'websocket') {
+        const url = new URL(endpoint(input.url, ['http:', 'https:', 'ws:', 'wss:']));
+        if (url.protocol === 'http:')
+            url.protocol = 'ws:';
+        if (url.protocol === 'https:')
+            url.protocol = 'wss:';
+        return Object.freeze({ transport: 'websocket', url: url.toString() });
+    }
+    if (input.transport === 'auto' && input.endpoints && typeof input.endpoints === 'object') {
+        return Object.freeze({
+            transport: 'auto',
+            endpoints: Object.freeze({
+                http: endpoint(input.endpoints.http, ['http:', 'https:']),
+                websocket: endpoint(input.endpoints.websocket, ['http:', 'https:', 'ws:', 'wss:']),
+            }),
+        });
+    }
+    throw new TypeError('Client target transport is invalid.');
+}
+export function targetKey(target) {
+    return target.transport === 'auto'
+        ? `auto\u0000${target.endpoints.http}\u0000${target.endpoints.websocket}`
+        : `${target.transport}\u0000${target.url}`;
+}
+function endpoint(input, protocols) {
+    if (typeof input !== 'string')
+        throw new TypeError('Client target URL must be a string.');
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch (cause) {
+        throw new TypeError('Client target URL is invalid.', { cause });
+    }
+    if (!protocols.includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '') {
+        throw new TypeError('Client target URL is invalid.');
+    }
+    return url.toString();
+}

package/dist/schema/admission.d.ts

@@ -0,0 +1,12 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+interface OutputContract {
+    safeParse(input: unknown): {
+        readonly success: true;
+        readonly data: Value;
+    } | {
+        readonly success: false;
+    };
+}
+/** Admit one value result through its Core-owned syscall contract. */
+export declare function acceptOutput<T>(contract: OutputContract, input: unknown): T;
+export {};

package/dist/schema/admission.js

@@ -0,0 +1,17 @@
+import * as portable from '@astrale-os/kernel-dsl/value';
+/** Admit one value result through its Core-owned syscall contract. */
+export function acceptOutput(contract, input) {
+    const value = portable.accept(input);
+    const parsed = contract.safeParse(value);
+    if (!parsed.success)
+        throw new TypeError('Kernel returned an invalid Schema result.');
+    return freeze(parsed.data);
+}
+function freeze(input) {
+    if (input !== null && typeof input === 'object' && !Object.isFrozen(input)) {
+        for (const value of Object.values(input))
+            freeze(value);
+        Object.freeze(input);
+    }
+    return input;
+}

package/dist/schema/contracts.d.ts

@@ -0,0 +1,12 @@
+import type { installation } from '@astrale-os/kernel-core/schema';
+import type { DesiredInstallation as CoreDesiredInstallation, InstallInput, InstallOutput, UninstallInput, UninstallOutput } from '@astrale-os/kernel-core/schema/kernel/syscalls/contracts';
+export type OperationId = installation.OperationId;
+/** Canonical caller input accepted by the Kernel install syscall. */
+export type DesiredInstallation = CoreDesiredInstallation;
+export type InstallRequest = InstallInput;
+/** Admitted terminal install receipt returned by the Kernel. */
+export type InstallReceipt = InstallOutput;
+/** Canonical caller input accepted by the Kernel uninstall syscall. */
+export type UninstallRequest = UninstallInput;
+/** Admitted terminal uninstall receipt returned by the Kernel. */
+export type UninstallReceipt = UninstallOutput;

package/dist/schema/contracts.js

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

package/dist/schema/index.d.ts

@@ -1,16 +1,3 @@
-export { SCHEMA_REGISTRY_BRAND, SchemaRegistry } from './registry.js';
-export { createSchemaClient } from './typed-client.js';
-export { createClassProxy } from './class-proxy.js';
-export { createNodeProxy, createInstanceProxy } from './node-proxy.js';
-export { resolveMethodKey } from './resolve.js';
-export { resolveCallArgs } from './call-args.js';
-export { createKnownInstanceDispatch, createKnownStaticDispatch } from './known-dispatch.js';
-export { extractMethodsByClass, extractMethodsByType } from './extract.js';
-export type { TypeMethods } from './extract.js';
-export { toFunctionSchemas } from './from-entries.js';
-export type { FunctionSchema } from './types.js';
-export type { SchemaPersistence } from './persistence.js';
-export type { ClassNames, ClassProxy, DefOf, InstanceDispatch, NodeProxy, ProxyCallOptions, ProxyCaller, SchemaTypedClient, StaticDispatch, TypeNames, } from './proxy-types.js';
-export { BindTypeMismatchError, createBoundNode, createNodeBinder, createSchemaBoundView, defaultCaller, resolveNeighbors, normalizeRef, } from './bound/index.js';
-export type { AnyBoundNode, BindCtx, BindOptions, BoundLinks, BoundNode, BoundNodeOperations, BoundPaged, BoundSnapshot, ClassHandle, CreatableClassNames, CreateProps, CreateSchemaBoundViewOpts, EdgeNames, EndpointsOf, NodeBinder, NodeRefInput, SchemaBoundView, SchemaClasses, } from './bound/index.js';
-//# sourceMappingURL=index.d.ts.map
+export { createSchema, type SchemaApi, type SchemaCall, type SchemaOptions, type ReadyInstallation, } from './schema.js';
+export { acceptOperationId, createOperationId } from './operation.js';
+export type { DesiredInstallation, InstallReceipt, InstallRequest, OperationId, UninstallReceipt, UninstallRequest, } from './contracts.js';

package/dist/schema/index.js

@@ -1,12 +1,2 @@
-export { SCHEMA_REGISTRY_BRAND, SchemaRegistry } from './registry.js';
-export { createSchemaClient } from './typed-client.js';
-export { createClassProxy } from './class-proxy.js';
-export { createNodeProxy, createInstanceProxy } from './node-proxy.js';
-export { resolveMethodKey } from './resolve.js';
-export { resolveCallArgs } from './call-args.js';
-export { createKnownInstanceDispatch, createKnownStaticDispatch } from './known-dispatch.js';
-export { extractMethodsByClass, extractMethodsByType } from './extract.js';
-export { toFunctionSchemas } from './from-entries.js';
-// ─── Schema-bound surface (SchemaBoundView / BoundNode / binder) ────────────
-export { BindTypeMismatchError, createBoundNode, createNodeBinder, createSchemaBoundView, defaultCaller, resolveNeighbors, normalizeRef, } from './bound/index.js';
-//# sourceMappingURL=index.js.map
+export { createSchema, } from './schema.js';
+export { acceptOperationId, createOperationId } from './operation.js';

package/dist/schema/introspection.d.ts

@@ -0,0 +1,5 @@
+import type { introspection as language } from '@astrale-os/kernel-core/schema';
+import type * as protocol from '@astrale-os/kernel-protocol/schema';
+import type { RequestOptions } from '../transport/index.js';
+import type { SchemaCall, SchemaOptions } from './schema.js';
+export declare function introspect<InputType extends language.Introspection>(invoke: SchemaCall, limits: SchemaOptions, request: InputType, options?: RequestOptions): Promise<protocol.installation.introspection.ResultFor<InputType>>;

package/dist/schema/introspection.js

@@ -0,0 +1,15 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { introspect as introspectRef } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import * as schema from '@astrale-os/kernel-protocol/schema';
+import { call } from '../client/index.js';
+const INTROSPECT_PATH = Path.project(introspectRef).raw;
+export async function introspect(invoke, limits, request, options) {
+    const result = await invoke(call(INTROSPECT_PATH, request), options);
+    if (result.kind !== 'binary') {
+        throw new TypeError('Schema introspection returned a non-binary result.');
+    }
+    if (result.value.mediaType !== schema.installation.introspection.MEDIA_TYPE) {
+        throw new TypeError('Schema introspection returned an unsupported media type.');
+    }
+    return schema.installation.introspection.decode(request, result.value.body, limits);
+}

package/dist/schema/operation.d.ts

@@ -0,0 +1,5 @@
+import type { OperationId } from './contracts.js';
+/** Accept one canonical lowercase RFC 9562 UUIDv4 operation identity. */
+export declare function acceptOperationId(input: unknown): OperationId;
+/** Allocate one cryptographically generated operation identity for a new lifecycle request. */
+export declare function createOperationId(): OperationId;

package/dist/schema/operation.js

@@ -0,0 +1,9 @@
+import * as installation from '@astrale-os/kernel-core/schema/installation';
+/** Accept one canonical lowercase RFC 9562 UUIDv4 operation identity. */
+export function acceptOperationId(input) {
+    return installation.acceptOperationId(input);
+}
+/** Allocate one cryptographically generated operation identity for a new lifecycle request. */
+export function createOperationId() {
+    return acceptOperationId(globalThis.crypto.randomUUID());
+}

package/dist/schema/schema.d.ts

@@ -0,0 +1,19 @@
+import type { introspection } from '@astrale-os/kernel-core/schema';
+import type * as protocolSchema from '@astrale-os/kernel-protocol/schema';
+import type { Call, Result } from '../client/index.js';
+import type { RequestOptions } from '../transport/index.js';
+import type { InstallReceipt, InstallRequest, UninstallReceipt, UninstallRequest } from './contracts.js';
+export type SchemaCall = (call: Call, options?: RequestOptions) => Promise<Result>;
+export interface SchemaOptions extends protocolSchema.installation.introspection.Limits {
+}
+export type ReadyInstallation = protocolSchema.installation.introspection.Installation & {
+    readonly state: 'ready';
+    readonly readiness: protocolSchema.installation.introspection.Digest;
+};
+export interface SchemaApi {
+    install(request: InstallRequest, options?: RequestOptions): Promise<InstallReceipt>;
+    uninstall(request: UninstallRequest, options?: RequestOptions): Promise<UninstallReceipt>;
+    introspect<Input extends introspection.Introspection>(request: Input, options?: RequestOptions): Promise<protocolSchema.installation.introspection.ResultFor<Input>>;
+}
+/** Bind the canonical Schema lifecycle syscalls to one caller-scoped value-call capability. */
+export declare function createSchema(call: SchemaCall, limits: SchemaOptions): SchemaApi;

package/dist/schema/schema.js

@@ -0,0 +1,43 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { installOutput, uninstallOutput, } from '@astrale-os/kernel-core/schema/kernel/syscalls/contracts';
+import { install, uninstall } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { call as invocation } from '../client/index.js';
+import { acceptOutput } from './admission.js';
+import { introspect as inspect } from './introspection.js';
+const INSTALL_PATH = Path.project(install).raw;
+const UNINSTALL_PATH = Path.project(uninstall).raw;
+/** Bind the canonical Schema lifecycle syscalls to one caller-scoped value-call capability. */
+export function createSchema(call, limits) {
+    if (typeof call !== 'function')
+        throw new TypeError('Schema call capability is invalid.');
+    const admittedLimits = admitLimits(limits);
+    return Object.freeze({
+        async install(request, options) {
+            const output = value(await call(invocation(INSTALL_PATH, request), options));
+            return acceptOutput(installOutput, output);
+        },
+        async uninstall(request, options) {
+            const output = value(await call(invocation(UNINSTALL_PATH, request), options));
+            return acceptOutput(uninstallOutput, output);
+        },
+        async introspect(request, options) {
+            return inspect(call, admittedLimits, request, options);
+        },
+    });
+}
+function value(result) {
+    if (result.kind !== 'value')
+        throw new TypeError('Schema syscall returned a non-value result.');
+    return result.value;
+}
+function admitLimits(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        !Number.isSafeInteger(input.maximumPublicationBytes) ||
+        input.maximumPublicationBytes < 1 ||
+        !Number.isSafeInteger(input.maximumBundleBytes) ||
+        input.maximumBundleBytes < 1) {
+        throw new TypeError('Schema introspection limits are invalid.');
+    }
+    return Object.freeze({ ...input });
+}

package/dist/session/bound.d.ts

@@ -1,11 +1,44 @@
-import type { CredentialInput } from '@astrale-os/kernel-core';
-import type { FnMap } from '../client/fn-map.js';
-import type { ClientSession } from './client-session.js';
-import type { BoundClientSessionOptions, BoundClientSessionView } from './types.js';
+import type { IssuerId } from '@astrale-os/kernel-core/auth';
+import type { ReadyInstallation } from '../schema/index.js';
+import type { SessionControlOptions } from './context/index.js';
+import type { CallableReference, InputOfReference, OutputOfReference } from './reference.js';
+import type { SessionRequestOptions } from './routing/index.js';
+import type { ViewCatalog } from './views/index.js';
+import { type AuthApi } from '../auth/index.js';
+import { type Binary, type Call, type Input, type Result, type Stream } from '../client/index.js';
+import { type GraphApi } from '../graph/index.js';
+/** Exact live Session surface captured by one credential-bound Kernel view. */
+export interface BoundSessionSource {
+    readonly kernel: IssuerId;
+    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<Stream>;
+    binary(call: Call, options?: SessionRequestOptions): Promise<Binary>;
+    installation(origin: string, options?: SessionControlOptions): Promise<ReadyInstallation>;
+    viewsFor(target: Parameters<import('./session.js').ClientSession['viewsFor']>[0], options?: SessionControlOptions): Promise<ViewCatalog>;
+}
+export interface BoundSessionControls {
+    readonly signal: AbortSignal;
+    /** Absolute Unix time in milliseconds. */
+    readonly deadline: number;
+}
 /**
- * Credential-bound view over a `ClientSession`. Every dispatch primitive delegates
- * to the underlying ClientSession with `opts.credential` replaced by the captured
- * credential. `as(next)` returns a fresh view — rebindings don't mutate.
+ * Credential-bound Kernel operations over one caller-owned ClientSession.
+ *
+ * The view owns no credential, transport, route cache, or lifecycle. Its source Session owns all of
+ * those concerns and closing that Session invalidates every operation exposed here.
  */
-export declare function createBoundSessionView<M extends FnMap>(session: ClientSession<M>, credential: CredentialInput | (() => CredentialInput), opts?: BoundClientSessionOptions): BoundClientSessionView<M>;
-//# sourceMappingURL=bound.d.ts.map
+export interface BoundClientSession extends GraphApi {
+    readonly kernel: IssuerId;
+    readonly auth: AuthApi;
+    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<Stream>;
+    binary(call: Call, options?: SessionRequestOptions): Promise<Binary>;
+    installation(origin: string, options?: SessionControlOptions): Promise<ReadyInstallation>;
+    viewsFor: BoundSessionSource['viewsFor'];
+}
+/** Capture one Session into the ordinary graph, auth, and invocation Kernel journey. */
+export declare function bindSession(source: BoundSessionSource, controls?: BoundSessionControls): BoundClientSession;