@astrale-os/kernel-client 0.2.0

package/dist/client/config.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Client configuration and per-call options.
+ *
+ * Two orthogonal axes: `transport` (the pipe — http/ws/auto) × `protocol`
+ * (the message shape — envelope/auto). `route` is HTTP-only, so
+ * `protocol: 'auto'` degrades to envelope on WS. `binary` and `batch` are
+ * HTTP-only regardless of `transport`. Defaults: `'http'` + `'envelope'`.
+ */
+import type { KernelRetryOptions } from '../pacer/retry';
+import type { SchemaRegistry } from '../schema/registry';
+import type { FunctionSchema } from '../schema/types';
+import type { ClientHooks } from './hooks';
+/** Minimal logger shape — a subset of `Console`. Defaults to `console`. */
+export type ClientLogger = Pick<Console, 'error' | 'warn'>;
+export type ClientConfig = {
+    /** Kernel URL. One client = one kernel — no pool. */
+    url: string;
+    /** Wire codec preference. Default `'json'`. */
+    codec?: 'json' | 'msgpack';
+    /**
+     * Default request timeout in ms. `0` or omitted = **no timeout** — the
+     * client never imposes one by default, so a CLI command against a
+     * dead server doesn't sit spinning for seconds the caller didn't ask
+     * for. Opt in explicitly per-client or per-call (`CallOptions.timeout`).
+     */
+    requestTimeout?: number;
+    /**
+     * Retry policy for transient wire failures (5xx, 429). **Default: no
+     * retry** — a failed call returns the failure immediately. Callers
+     * that want retries configure `kernelRetry` themselves or pass a
+     * policy here.
+     */
+    retry?: KernelRetryOptions;
+    /**
+     * Preloaded schemas or an external `SchemaRegistry`. Passing a registry
+     * lets multiple clients share one (saves / loads are visible across all).
+     * Passing an array loads an internal registry at construction.
+     */
+    schema?: FunctionSchema[] | SchemaRegistry;
+    /** Custom `fetch` (testing, environment shims). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** Lifecycle hooks — pure observation (see `client/hooks.ts`). */
+    hooks?: ClientHooks;
+    /** Default transport (see `CallTransport`). Default `'http'`. */
+    defaultTransport?: CallTransport;
+    /**
+     * Default protocol. `'envelope'` always speaks the kernel envelope;
+     * `'auto'` prefers route if the schema has a `RouteBinding` and the
+     * transport is HTTP, else falls through to envelope. Default `'envelope'`.
+     */
+    defaultProtocol?: Protocol;
+    /**
+     * Logger used for hook-failure diagnostics. Only the error's name +
+     * message are surfaced — see `KernelClient.logHookError`. Default: `console`.
+     */
+    logger?: ClientLogger;
+};
+/**
+ * Transport the call rides over.
+ *
+ * - `'http'` — always HTTP.
+ * - `'ws'`   — always WebSocket; connect failure throws `ConnectionError`.
+ * - `'auto'` — WS-first with HTTP fallback on initial connect failure.
+ *   Once a frame round-trips, commits to WS (mid-session closures throw —
+ *   no silent downgrade for long-running consumers). Signal stays on HTTP
+ *   until WS is proven: fire-and-forget can't communicate fallback.
+ *
+ * **Caveat:** the browser `WebSocket` API reports all handshake failures
+ * (server doesn't speak WS, auth reject, WAF, origin mismatch) as the same
+ * error. `'auto'` treats every connect failure as WS-unsupported and sticks
+ * on HTTP for the client's lifetime — an auth-related failure gets masked.
+ * Consumers needing WS-specific errors should use `transport: 'ws'`.
+ */
+export type CallTransport = 'http' | 'ws' | 'auto';
+/**
+ * Message-shape preference. `envelope` forces the kernel envelope;
+ * `auto` uses the schema's `RouteBinding` when present and the
+ * transport is HTTP, else envelope.
+ */
+export type Protocol = 'envelope' | 'auto';
+export type CallOptions = {
+    /** Per-call timeout override (ms). */
+    timeout?: number;
+    /** Abort signal — propagates through the controller to the transport. */
+    signal?: AbortSignal;
+    /** Class context for instance-method schema resolution (e.g. `'Document'`). */
+    class?: string;
+    /**
+     * Override target URL. Used by an orchestrator (layer D) to retarget
+     * a call after a redirect. Supports `{placeholder}` substitution from
+     * params, same as `remoteUrl`.
+     */
+    url?: string;
+    /**
+     * Per-call transport override. Applies to hop-1 only — redirect follow-ups
+     * pick their transport from the schema of the new target.
+     */
+    transport?: CallTransport;
+    /**
+     * Per-call protocol override. `'auto'` resolves to route when the
+     * schema has a binding AND `transport === 'http'`; else envelope.
+     */
+    protocol?: Protocol;
+    /**
+     * Caller-provided correlation id — threaded into every `ClientHooks`
+     * context and onto any thrown error's `.details.correlationId`.
+     */
+    correlationId?: string;
+    /** Target-of-call for instance methods. Forwarded as `KernelRequest.self`. */
+    self?: string;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/client/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/client/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,CAAA;AAE1D,MAAM,MAAM,YAAY,GAAG;IACzB,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IAEX,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,cAAc,CAAA;IAE1C,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAEpB,kEAAkE;IAClE,KAAK,CAAC,EAAE,WAAW,CAAA;IAEnB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,aAAa,CAAA;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAA;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAA;AAElD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAA;AAE1C,MAAM,MAAM,WAAW,GAAG;IACxB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,yEAAyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,CAAA;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA"}

package/dist/client/config.js

@@ -0,0 +1,10 @@
+/**
+ * Client configuration and per-call options.
+ *
+ * Two orthogonal axes: `transport` (the pipe — http/ws/auto) × `protocol`
+ * (the message shape — envelope/auto). `route` is HTTP-only, so
+ * `protocol: 'auto'` degrades to envelope on WS. `binary` and `batch` are
+ * HTTP-only regardless of `transport`. Defaults: `'http'` + `'envelope'`.
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/client/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/client/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/client/fn-map.d.ts

@@ -0,0 +1,61 @@
+import type { CallRedirection } from '@astrale-os/kernel-api';
+import type { BinaryResponse } from '../transport/binary';
+import type { WireMeta } from '../wire/meta';
+/**
+ * A single function entry in the type map. `TKind` is required — codegen
+ * always writes it; defaulting here would only obscure intent.
+ */
+export type FnEntry<TParams, TResult, TKind extends 'call' | 'stream' | 'signal' | 'binary'> = {
+    params: TParams;
+    result: TResult;
+    kind: TKind;
+};
+/** Function map: method ref → FnEntry. Type parameter for `KernelClient<M>`. */
+export type FnMap = Record<string, FnEntry<unknown, unknown, 'call' | 'stream' | 'signal' | 'binary'>>;
+type FnsOfKind<M extends FnMap, K extends 'call' | 'stream' | 'signal' | 'binary'> = {
+    [Path in keyof M]: M[Path]['kind'] extends K ? Path : never;
+}[keyof M] & string;
+/**
+ * Wildcard-map detector. When `M` is the bare `FnMap` (no literal keys),
+ * `keyof M` is `string`, so `string extends keyof M` is `true` and the
+ * `*Fns<M>` aliases collapse to `string` — letting untyped consumers pass
+ * any method ref. For typed maps with literal keys, the conditional is
+ * `false` and the kind discrimination kicks in as before.
+ */
+type IsWildcardMap<M extends FnMap> = string extends keyof M ? true : false;
+export type CallFns<M extends FnMap> = IsWildcardMap<M> extends true ? string : FnsOfKind<M, 'call'>;
+export type StreamFns<M extends FnMap> = IsWildcardMap<M> extends true ? string : FnsOfKind<M, 'stream'>;
+export type SignalFns<M extends FnMap> = IsWildcardMap<M> extends true ? string : FnsOfKind<M, 'signal'>;
+export type BinaryFns<M extends FnMap> = IsWildcardMap<M> extends true ? string : FnsOfKind<M, 'binary'>;
+/** `client.send(...)` return — value or redirect. */
+export type SendResult<T> = {
+    kind: 'value';
+    value: T;
+    meta: WireMeta;
+} | {
+    kind: 'redirect';
+    redirection: CallRedirection;
+    meta: WireMeta;
+};
+/** `client.sendStream(...)` return — stream of chunks or on-open redirect. */
+export type SendStreamResult<T> = {
+    kind: 'stream';
+    chunks: AsyncIterable<T>;
+    meta: WireMeta;
+} | {
+    kind: 'redirect';
+    redirection: CallRedirection;
+    meta: WireMeta;
+};
+/** `client.sendBinary(...)` return — binary response or redirect. */
+export type SendBinaryResult = {
+    kind: 'binary';
+    response: BinaryResponse;
+    meta: WireMeta;
+} | {
+    kind: 'redirect';
+    redirection: CallRedirection;
+    meta: WireMeta;
+};
+export {};
+//# sourceMappingURL=fn-map.d.ts.map

package/dist/client/fn-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-map.d.ts","sourceRoot":"","sources":["../../src/client/fn-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAI5C;;;GAGG;AACH,MAAM,MAAM,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,IAAI;IAC7F,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,KAAK,CAAA;CACZ,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,KAAK,GAAG,MAAM,CACxB,MAAM,EACN,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC,CACnE,CAAA;AAID,KAAK,SAAS,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,SAAS,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,IAAI;KAClF,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,KAAK;CAC5D,CAAC,MAAM,CAAC,CAAC,GACR,MAAM,CAAA;AAER;;;;;;GAMG;AACH,KAAK,aAAa,CAAC,CAAC,SAAS,KAAK,IAAI,MAAM,SAAS,MAAM,CAAC,GAAG,IAAI,GAAG,KAAK,CAAA;AAE3E,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AACpG,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,KAAK,IACnC,aAAa,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AACjE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,KAAK,IACnC,aAAa,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AACjE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,KAAK,IACnC,aAAa,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AAUjE,qDAAqD;AACrD,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEtE,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEtE,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA"}

package/dist/client/fn-map.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fn-map.js.map

package/dist/client/fn-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-map.js","sourceRoot":"","sources":["../../src/client/fn-map.ts"],"names":[],"mappings":""}

package/dist/client/freeze.d.ts

@@ -0,0 +1,32 @@
+import type { SendBinaryResult, SendResult, SendStreamResult } from './fn-map';
+/**
+ * Freeze the envelope of a `Send*Result` so observers can't
+ * structurally rewrite it. Frozen:
+ *
+ *   - the outer result (so `result.kind = 'redirect'` throws)
+ *   - `result.meta` (so `meta.durationMs = 0` throws)
+ *   - `result.meta.wire` and its `wire.headers` Record (HTTP variant)
+ *
+ * NOT frozen (by design — these are consumable / caller-owned):
+ *
+ *   - `result.value` for `kind: 'value'` — payload data; caller may
+ *     mutate it without affecting the client. Hooks that mutate this
+ *     still see their changes in their own scope but do not retarget
+ *     the client.
+ *   - `result.redirection` for `kind: 'redirect'` — kept mutable for
+ *     the same reason; an orchestrator may normalise the URL before
+ *     retrying.
+ *   - `result.chunks` for `kind: 'stream'` — the async iterable must
+ *     stay live so the caller can consume it.
+ *   - `result.response` for `kind: 'binary'` — body is a
+ *     `ReadableStream` or `Uint8Array`; freezing the wrapper would not
+ *     add safety and could surprise bindings that attach properties.
+ *
+ * The structural freeze closes spec §10's "observation, not
+ * transformation" guarantee: a hook that tries
+ * `ctx.result.kind = 'x'` or `ctx.result.meta.transport = 'y'` throws
+ * `TypeError` in strict mode instead of silently mutating the shape a
+ * subsequent hook or the caller depends on.
+ */
+export declare function freezeResult<R extends SendResult<unknown> | SendStreamResult<unknown> | SendBinaryResult>(result: R): R;
+//# sourceMappingURL=freeze.d.ts.map

package/dist/client/freeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/client/freeze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,gBAAgB,EAC5E,MAAM,EAAE,CAAC,GAAG,CAAC,CASd"}

package/dist/client/freeze.js

@@ -0,0 +1,42 @@
+/**
+ * Freeze the envelope of a `Send*Result` so observers can't
+ * structurally rewrite it. Frozen:
+ *
+ *   - the outer result (so `result.kind = 'redirect'` throws)
+ *   - `result.meta` (so `meta.durationMs = 0` throws)
+ *   - `result.meta.wire` and its `wire.headers` Record (HTTP variant)
+ *
+ * NOT frozen (by design — these are consumable / caller-owned):
+ *
+ *   - `result.value` for `kind: 'value'` — payload data; caller may
+ *     mutate it without affecting the client. Hooks that mutate this
+ *     still see their changes in their own scope but do not retarget
+ *     the client.
+ *   - `result.redirection` for `kind: 'redirect'` — kept mutable for
+ *     the same reason; an orchestrator may normalise the URL before
+ *     retrying.
+ *   - `result.chunks` for `kind: 'stream'` — the async iterable must
+ *     stay live so the caller can consume it.
+ *   - `result.response` for `kind: 'binary'` — body is a
+ *     `ReadableStream` or `Uint8Array`; freezing the wrapper would not
+ *     add safety and could surprise bindings that attach properties.
+ *
+ * The structural freeze closes spec §10's "observation, not
+ * transformation" guarantee: a hook that tries
+ * `ctx.result.kind = 'x'` or `ctx.result.meta.transport = 'y'` throws
+ * `TypeError` in strict mode instead of silently mutating the shape a
+ * subsequent hook or the caller depends on.
+ */
+export function freezeResult(result) {
+    // Freeze the meta first so nested wire field is also frozen.
+    Object.freeze(result.meta);
+    if (result.meta.wire)
+        Object.freeze(result.meta.wire);
+    // Headers are already frozen by `headersToRecord`, but re-freezing a
+    // frozen object is a no-op and keeps the guarantee local.
+    const wire = result.meta.wire;
+    if (wire.kind === 'http')
+        Object.freeze(wire.headers);
+    return Object.freeze(result);
+}
+//# sourceMappingURL=freeze.js.map

package/dist/client/freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.js","sourceRoot":"","sources":["../../src/client/freeze.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,YAAY,CAE1B,MAAS;IACT,6DAA6D;IAC7D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrD,qEAAqE;IACrE,0DAA0D;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAA;IAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;QAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC"}

package/dist/client/hooks.d.ts

@@ -0,0 +1,49 @@
+import type { CredentialInput } from '@astrale-os/kernel-core';
+import type { TransportName, WireMeta } from '../wire/meta';
+import type { SendBinaryResult, SendResult, SendStreamResult } from './fn-map';
+/**
+ * Lifecycle hooks — pure observation. Return values are ignored; throws
+ * are caught, logged, and the call proceeds unchanged. The result object
+ * handed to `onAfterReceive` is `Object.freeze`d, so hooks cannot mutate
+ * what the caller sees.
+ *
+ * Signals (fire-and-forget) flow through `onAfterSignal`, not
+ * `onAfterReceive` — signals have no response meta and a string-in-a-union
+ * would force every consumer to narrow away the non-object case.
+ */
+export type ClientHooks = {
+    onBeforeSend?: (ctx: BeforeSendCtx) => void | Promise<void>;
+    onAfterReceive?: (ctx: AfterReceiveCtx) => void | Promise<void>;
+    onAfterSignal?: (ctx: AfterSignalCtx) => void | Promise<void>;
+    onError?: (ctx: ErrorCtx) => void | Promise<void>;
+    onStreamFrame?: (ctx: StreamFrameCtx) => void | Promise<void>;
+};
+export type BeforeSendCtx = {
+    method: string;
+    params: unknown;
+    credential: CredentialInput;
+    transport: TransportName;
+    url: string;
+    correlationId?: string;
+};
+export type AfterReceiveCtx = BeforeSendCtx & {
+    result: SendResult<unknown> | SendStreamResult<unknown> | SendBinaryResult;
+    meta: WireMeta;
+};
+export type AfterSignalCtx = BeforeSendCtx & {
+    /** Client-side timestamp when the signal was dispatched onto the wire. */
+    dispatchedAt: number;
+};
+export type ErrorCtx = BeforeSendCtx & {
+    error: Error;
+    /** Present when the error arose post-decode; absent on connect/timeout. */
+    meta?: WireMeta;
+};
+export type StreamFrameCtx = BeforeSendCtx & {
+    /** Zero-based index of the chunk in the stream. */
+    index: number;
+    data: unknown;
+    /** Stream-open meta — frozen from the opening `SendStreamResult.meta`. */
+    meta: WireMeta;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/client/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/client/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAE9E;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9D,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,eAAe,CAAA;IAC3B,SAAS,EAAE,aAAa,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC5C,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAA;IAC1E,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG;IAC3C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG;IACrC,KAAK,EAAE,KAAK,CAAA;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG;IAC3C,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,0EAA0E;IAC1E,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA"}

package/dist/client/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/client/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/client/hooks.ts"],"names":[],"mappings":""}

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+export { KernelClient } from './client';
+export type { BoundClientView } from './bound';
+export type { CallOptions, ClientConfig, Protocol, CallTransport } from './config';
+export type { AfterReceiveCtx, AfterSignalCtx, BeforeSendCtx, ClientHooks, ErrorCtx, StreamFrameCtx, } from './hooks';
+export type { BinaryFns, CallFns, FnEntry, FnMap, SendBinaryResult, SendResult, SendStreamResult, SignalFns, StreamFns, } from './fn-map';
+export type { BatchResults, TypedBatchRequest } from './batch';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAClF,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,SAAS,CAAA;AAChB,YAAY,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,KAAK,EACL,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,SAAS,GACV,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA"}

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { KernelClient } from './client';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA"}

package/dist/delegation/cache.d.ts

@@ -0,0 +1,133 @@
+import type { CredentialInput } from '@astrale-os/kernel-core';
+import type { SelfIdentityExpr, UnresolvedIdentityExpr } from '@astrale-os/kernel-core/expression';
+/**
+ * Result a mint function returns. `credential` is what ClientSession hands to
+ * the wire; `ttl` (seconds) controls caching — omit to use
+ * `DelegationCacheConfig.ttl` (default 300), pass `0` to opt out of
+ * caching for this mint.
+ */
+export type DelegationMintResult = {
+    credential: CredentialInput;
+    ttl?: number;
+};
+/**
+ * Mint function — resolves a delegated credential for
+ * `(audience, delegation, attestation)`. Matches the server-side
+ * `MintDelegationParams` triple in
+ * `kernel/ports/authentication/authentication.port.ts` — the cache
+ * forwards each field to the mint verbatim; no reduction, no flattening.
+ *
+ * ClientSession's default mint calls `identity.mintDelegation` through the
+ * default kernel; consumers can override (pre-shared tokens, HSM,
+ * offline signing). Must reject on failure — the cache treats rejection
+ * as "don't cache" and every waiter sees the error.
+ */
+export type DelegationMintFn = (audience: string, delegation: UnresolvedIdentityExpr, attestation: SelfIdentityExpr | undefined) => Promise<DelegationMintResult>;
+/**
+ * Config for `DelegationCache`. `mint` is required — without it, the
+ * cache cannot resolve misses.
+ */
+export type DelegationCacheConfig = {
+    mint: DelegationMintFn;
+    /**
+     * Default TTL (seconds) applied when `mint` returns no explicit TTL.
+     * Default: `300`.
+     */
+    ttl?: number;
+    /**
+     * Maximum cached entries. LRU eviction when exceeded. Default: `64`.
+     */
+    maxSize?: number;
+    /**
+     * Clock source. Override for deterministic tests. Defaults to
+     * `() => Date.now() / 1000` — epoch seconds.
+     */
+    now?: () => number;
+};
+/**
+ * TTL-keyed credential cache with concurrent-mint deduplication. Spec §9.2.
+ *
+ * **Concurrent-mint invariant:** two concurrent `get(audience, delegation,
+ * attestation)` calls for the same structural triple share a single mint
+ * dispatch. On success, every waiter receives the same credential and the
+ * result is cached. On rejection, every waiter sees the rejection and the
+ * cache is NOT populated — subsequent calls re-attempt minting.
+ *
+ * **Structural key:** `delegation` and `attestation` are canonicalized
+ * by a deterministic JSON encoding (sorted keys; array order preserved —
+ * see `canonicalEncode` docstring). Policies returning fresh-but-equal
+ * objects on every call hit the same cache entry.
+ *
+ * **Attestation distinct from undefined:** `undefined` attestation and
+ * `{ kind: 'identity', self: true }` attestation are distinct keys (§9.2.1)
+ * even though the kernel adapter defaults the former to the latter at
+ * the wire — they produce distinguishable outer-envelope claims.
+ */
+export declare class DelegationCache {
+    private readonly entries;
+    private readonly inFlight;
+    private readonly byAudience;
+    private readonly mint;
+    private readonly defaultTtl;
+    private readonly maxSize;
+    private readonly now;
+    private clock;
+    private clearEpoch;
+    constructor(config: DelegationCacheConfig);
+    /**
+     * Returns a delegated credential for `(audience, delegation, attestation)`.
+     * Cache hit returns synchronously-resolved; miss coalesces a single mint
+     * across concurrent callers on the same structural key.
+     *
+     * Throws `DelegationMintError` (wrapping the mint's cause) on mint
+     * failure. The failure is NOT cached.
+     */
+    get(audience: string, delegation: UnresolvedIdentityExpr, attestation?: SelfIdentityExpr): Promise<CredentialInput>;
+    /**
+     * Manually insert an entry. Used by consumers minting through a
+     * custom path outside `get`'s default mint flow.
+     */
+    set(audience: string, credential: CredentialInput, ttl: number, delegation: UnresolvedIdentityExpr, attestation?: SelfIdentityExpr): void;
+    /** Remove one entry. Idempotent — no-op for absent keys. */
+    evict(audience: string, delegation: UnresolvedIdentityExpr, attestation?: SelfIdentityExpr): void;
+    /**
+     * Remove every entry for `audience`, regardless of delegation /
+     * attestation shape. Returns the number of entries removed.
+     * Idempotent — returns `0` for unknown audiences.
+     *
+     * Bulk invalidation primitive: a host whose user revokes consent for
+     * an audience calls this without enumerating every
+     * `(delegation, attestation)` combination it minted.
+     */
+    evictAudience(audience: string): number;
+    /**
+     * Drop every cached entry. Does NOT abort in-flight mints — they
+     * resolve as usual but their results bypass the now-cleared cache.
+     */
+    clear(): void;
+    /** Entry count. Useful for tests; not a contract for production flow. */
+    get size(): number;
+    private insert;
+    private indexKey;
+    private deleteEntry;
+    private evictLeastRecentlyUsed;
+}
+/**
+ * Build a deterministic cache key from `(audience, delegation, attestation)`.
+ *
+ * The `delegation` and `attestation` trees are serialised through
+ * `canonicalEncode`, which:
+ *   - Sorts object keys alphabetically at every node (so
+ *     `{ kind, expr }` and `{ expr, kind }` collide).
+ *   - Preserves array order (union/intersect/exclude operands are
+ *     position-sensitive in the canonical form; `Scope[]` inside
+ *     `{ kind: 'scope' }` is also position-preserving — scope sorting
+ *     is the caller's choice, not the cache's, per spec §9.2.1).
+ *   - Emits `#none` for absent attestation (distinct from any present
+ *     `SelfIdentityExpr` including `{ kind: 'identity', self: true }`).
+ *
+ * Exported so ClientSession's `#pendingMints` table stays keyed identically
+ * without duplicating the key-shape logic.
+ */
+export declare function delegationCacheKey(audience: string, delegation: UnresolvedIdentityExpr, attestation: SelfIdentityExpr | undefined): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/delegation/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/delegation/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAA;AAIlG;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,eAAe,CAAA;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAClC,WAAW,EAAE,gBAAgB,GAAG,SAAS,KACtC,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAElC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,gBAAgB,CAAA;IACtB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAK5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,KAAK,CAAI;IAIjB,OAAO,CAAC,UAAU,CAAI;IAEtB,YAAY,MAAM,EAAE,qBAAqB,EAQxC;IAED;;;;;;;OAOG;IACG,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAClC,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA8C1B;IAED;;;OAGG;IACH,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,eAAe,EAC3B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,sBAAsB,EAClC,WAAW,CAAC,EAAE,gBAAgB,GAC7B,IAAI,CASN;IAED,4DAA4D;IAC5D,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAClC,WAAW,CAAC,EAAE,gBAAgB,GAC7B,IAAI,CAGN;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOtC;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAIZ;IAED,yEAAyE;IACzE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,sBAAsB;CAW/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAClC,WAAW,EAAE,gBAAgB,GAAG,SAAS,GACxC,MAAM,CAIR"}