@net-mesh/core 0.22.0 → 0.24.0

package/mesh_rpc.d.ts

@@ -72,11 +72,240 @@ export interface RawMeshRpc {
     call(targetNodeId: bigint, service: string, request: Buffer, opts?: CallOptions): Promise<Buffer>;
     callService(service: string, request: Buffer, opts?: CallOptions): Promise<Buffer>;
     callStreaming(targetNodeId: bigint, service: string, request: Buffer, opts?: CallOptions): Promise<RawRpcStream>;
+    /**
+     * Open a client-streaming call. Returns a `RawClientStreamCall`
+     * — push chunks via `send`, then `finish` to await the terminal
+     * response.
+     */
+    callClientStream(targetNodeId: bigint, service: string, opts?: CallOptions): Promise<RawClientStreamCall>;
+    /**
+     * Register a client-streaming handler. The handler receives a
+     * `RawRequestStream` and returns the terminal response as a
+     * Buffer. Throw `appError(code, body)` to surface a typed
+     * Application status.
+     */
+    serveClientStream(service: string, handler: (stream: RawRequestStream) => Promise<Buffer>): ServeHandle;
+    /**
+     * Open a duplex call. Both `requestWindowInitial` (upload flow
+     * control) and `streamWindowInitial` (download flow control)
+     * on `CallOptions` are independently opt-in.
+     */
+    callDuplex(targetNodeId: bigint, service: string, opts?: CallOptions): Promise<RawDuplexCall>;
+    /**
+     * Register a duplex handler. The napi side passes a 2-tuple
+     * `[stream, sink]` to the handler (per the
+     * `DuplexHandlerArgs::ToNapiValue` impl in the napi binding).
+     * Handler returns a terminal Buffer that the substrate discards;
+     * intermediate chunks come from `sink.send`. Throw
+     * `appError(code, body)` to surface a typed Application status.
+     */
+    serveDuplex(service: string, handler: (args: [RawRequestStream, RawResponseSink]) => Promise<Buffer>): ServeHandle;
     findServiceNodes(service: string): bigint[];
     /** Mint a fresh cancel token (`bigint`). */
     reserveCancelToken(): bigint;
     /** Abort the in-flight call associated with `token`. Idempotent. */
     cancelCall(token: bigint): void;
+    /**
+     * Install (or clear with `null` / `undefined`) the caller-side
+     * nRPC observer. The handler receives the napi POD
+     * (`RawRpcCallEvent`); the typed wrapper layer normalizes into
+     * a tagged-union {@link RpcCallEvent} before reaching user code.
+     * See `TypedMeshRpc.setObserver` for the locked-decision
+     * contract.
+     */
+    setObserver(observer: ((evt: RawRpcCallEvent) => void) | null | undefined): void;
+    /** Snapshot the per-service nRPC metrics registry. */
+    metricsSnapshot(): RpcMetricsSnapshot;
+}
+/**
+ * Status discriminant for an observed RPC call. Match on `kind`
+ * before reading other fields; this is a string-tagged union
+ * because the napi POD layer doesn't support TS discriminated
+ * unions natively (the napi side flattens it to `statusKind:
+ * string` + `statusMessage?: string` — see {@link RpcCallEvent}).
+ */
+export type RpcCallStatus = {
+    kind: 'ok';
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'canceled';
+};
+/**
+ * Single observed RPC call boundary. Surfaced to the observer
+ * callback installed via `TypedMeshRpc.setObserver`. Mirrors the
+ * substrate's `RpcCallEvent` field-by-field — the typed wrapper
+ * reconstructs the `RpcCallStatus` tagged union from the napi
+ * POD's flat `statusKind` / `statusMessage` pair so user code
+ * sees a TS-idiomatic discriminated union.
+ */
+export interface RpcCallEvent {
+    /** 64-bit node id of the calling node. */
+    caller: bigint;
+    /** 64-bit node id of the responding node. */
+    callee: bigint;
+    /** Service / method name. */
+    method: string;
+    /** Elapsed time in milliseconds. */
+    latencyMs: number;
+    /** Tagged-union outcome. Match on `status.kind`. */
+    status: RpcCallStatus;
+    /** Wire payload size of the request body (0 when not available). */
+    requestBytes: number;
+    /** Wire payload size of the response body (0 when not available). */
+    responseBytes: number;
+    /** v1 only emits `"outbound"`; `"inbound"` is reserved. */
+    direction: 'outbound' | 'inbound';
+    /** Unix-ms timestamp captured at fire time. */
+    tsUnixMs: bigint;
+}
+/**
+ * Status-kind discriminants emitted on `RawRpcCallEvent.statusKind`
+ * and consumed when normalizing into the tagged-union
+ * {@link RpcCallStatus}. Prefer these constants over hard-coding
+ * the string literal in `if (evt.statusKind === '...')` checks —
+ * a typo on the literal silently never fires.
+ *
+ * Named `STATUS_KIND_*` to disambiguate from the wire-level
+ * `STATUS_*` u16 status codes used by `RpcServerError`.
+ */
+export declare const STATUS_KIND_OK: "ok";
+export declare const STATUS_KIND_ERROR: "error";
+export declare const STATUS_KIND_TIMEOUT: "timeout";
+export declare const STATUS_KIND_CANCELED: "canceled";
+/** Direction-kind discriminants on `RawRpcCallEvent.direction`. */
+export declare const DIRECTION_OUTBOUND: "outbound";
+export declare const DIRECTION_INBOUND: "inbound";
+export type StatusKind = typeof STATUS_KIND_OK | typeof STATUS_KIND_ERROR | typeof STATUS_KIND_TIMEOUT | typeof STATUS_KIND_CANCELED;
+export type DirectionKind = typeof DIRECTION_OUTBOUND | typeof DIRECTION_INBOUND;
+/**
+ * Raw napi observer event shape (POD with flat `statusKind` /
+ * `statusMessage` strings). Internal — the typed wrapper
+ * normalizes it into {@link RpcCallEvent} before reaching user
+ * code. Exported so test stubs can construct events directly.
+ */
+export interface RawRpcCallEvent {
+    caller: bigint;
+    callee: bigint;
+    method: string;
+    latencyMs: number;
+    statusKind: StatusKind;
+    statusMessage?: string | null;
+    requestBytes: number;
+    responseBytes: number;
+    direction: DirectionKind;
+    tsUnixMs: bigint;
+}
+/**
+ * Per-service caller + server-side nRPC counters at a point in
+ * time. Element of `RpcMetricsSnapshot.services`. All `bigint`
+ * fields are direct u64 counters; `inFlight` and `handlerInFlight`
+ * are signed i64 to track concurrent calls without underflow.
+ */
+export interface ServiceMetrics {
+    service: string;
+    callsTotal: bigint;
+    errorsNoRoute: bigint;
+    errorsTimeout: bigint;
+    errorsServer: bigint;
+    errorsTransport: bigint;
+    inFlight: number;
+    latencySumNs: bigint;
+    latencyCount: bigint;
+    /**
+     * Cumulative histogram bucket counts; index `i` corresponds to
+     * the substrate's `DEFAULT_LATENCY_BUCKETS_SECS[i]`. Last entry
+     * is the `+Inf` bucket.
+     */
+    latencyBuckets: bigint[];
+    handlerInvocationsTotal: bigint;
+    handlerPanicsTotal: bigint;
+    handlerInFlight: number;
+    handlerDurationSumNs: bigint;
+    handlerDurationCount: bigint;
+    handlerDurationBuckets: bigint[];
+    streamingChunksEmittedTotal: bigint;
+    streamingChunksDroppedTotal: bigint;
+    capabilityDeniedTotal: bigint;
+}
+/**
+ * Snapshot of the per-service nRPC metrics registry. Returned by
+ * `TypedMeshRpc.metricsSnapshot`. Cheap — one DashMap iteration
+ * on the substrate side. Safe to collect on every Prometheus
+ * scrape.
+ */
+export interface RpcMetricsSnapshot {
+    /**
+     * One entry per service that has been called at least once
+     * since the mesh was created. Sorted by service name.
+     */
+    services: ServiceMetrics[];
+}
+/**
+ * Raw napi `ClientStreamCall` — minimal shape consumed by
+ * `TypedClientStreamCall`. Caller pushes typed chunks via `send`
+ * then awaits the terminal response with `finish`.
+ */
+export interface RawClientStreamCall {
+    send(body: Buffer): Promise<void>;
+    finish(): Promise<Buffer>;
+    callId(): Promise<bigint>;
+    flowControlled(): Promise<boolean>;
+    close(): Promise<void>;
+}
+/**
+ * Raw napi `JsRequestStream` — minimal shape consumed by
+ * `TypedRequestStream` server-side. Drain via `next()` until it
+ * returns `null` (clean EOF) or throws on terminal error.
+ *
+ * The diagnostic getters (`callerOrigin`, `callId`, `deadlineNs`,
+ * `headers`) are populated at handler-dispatch time and stable
+ * for the lifetime of the stream.
+ */
+export interface RawRequestStream {
+    next(): Promise<Buffer | null>;
+    readonly callerOrigin: bigint;
+    readonly callId: bigint;
+    readonly deadlineNs: bigint;
+    readonly headers: [string, Buffer][];
+}
+/**
+ * Raw napi `DuplexCall` — combined send + receive surface. Use
+ * `intoSplit` to separate into independent sink + stream halves.
+ */
+export interface RawDuplexCall {
+    send(body: Buffer): Promise<void>;
+    finishSending(): Promise<void>;
+    next(): Promise<Buffer | null>;
+    intoSplit(): Promise<[RawDuplexSink, RawDuplexStream]>;
+    callId(): Promise<bigint>;
+    flowControlled(): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** Send-half of a `RawDuplexCall` after `intoSplit`. */
+export interface RawDuplexSink {
+    send(body: Buffer): Promise<void>;
+    finish(): Promise<void>;
+    callId(): Promise<bigint>;
+    flowControlled(): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** Receive-half of a `RawDuplexCall` after `intoSplit`. */
+export interface RawDuplexStream {
+    next(): Promise<Buffer | null>;
+    callId(): Promise<bigint>;
+    close(): Promise<void>;
+}
+/**
+ * Raw napi `JsResponseSink` — outbound side surfaced to duplex
+ * server handlers. Non-async (try_send under the hood; drops on
+ * mpsc overflow). Returns `false` if the sink has been closed.
+ */
+export interface RawResponseSink {
+    send(body: Buffer): boolean;
 }
 /** Raw napi `RpcStream` — minimal shape consumed by `TypedRpcStream`. */
 export interface RawRpcStream {
@@ -136,6 +365,94 @@ export declare class TypedMeshRpc {
     callStreaming<Req = unknown, Resp = unknown>(targetNodeId: bigint, service: string, req: Req, opts?: CallOptions): Promise<TypedRpcStream<Resp>>;
     /** Pass-through to `MeshRpc.findServiceNodes`. */
     findServiceNodes(service: string): bigint[];
+    /**
+     * Open a typed client-streaming call. Returns a
+     * `TypedClientStreamCall<Req, Resp>` — push each request via
+     * `send(value)`, then `finish()` to drain the terminal
+     * response.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired end-to-end
+     * via the same `wireAbortSignal` helper unary calls use.
+     * `signal.aborted` triggers the substrate's
+     * `MeshNode::cancel(token)`, which drops the pending
+     * client-stream entry — the next `send()` / `finish()` observes
+     * a stream-closed error within bounded time, and the call's
+     * Drop emits CANCEL on the wire. Invoking `typedCall.close()`
+     * explicitly is still supported as the imperative cancel
+     * surface.
+     */
+    callClientStream<Req = unknown, Resp = unknown>(targetNodeId: bigint, service: string, opts?: CallOptions): Promise<TypedClientStreamCall<Req, Resp>>;
+    /**
+     * Register a typed client-streaming handler. The handler
+     * receives a `TypedRequestStream<Req>` (auto-decodes each
+     * inbound chunk to `Req`) and returns the terminal response
+     * `Resp` (encoded back to JSON before reaching the caller).
+     *
+     * Decode failure on a chunk surfaces from `stream.next()` as
+     * `nrpc:codec_decode:` — the handler may catch it (e.g. skip
+     * the bad chunk) or let it propagate. Letting it propagate
+     * surfaces to the caller as `RpcServerError(Internal)`; the
+     * handler may instead wrap it with `appError(NRPC_TYPED_BAD_REQUEST,
+     * ...)` to signal a typed bad-request status code.
+     */
+    serveClientStream<Req = unknown, Resp = unknown>(service: string, handler: (stream: TypedRequestStream<Req>) => Promise<Resp>): ServeHandle;
+    /**
+     * Open a typed duplex call. Returns a `TypedDuplexCall<Req,
+     * Resp>` — push typed requests via `send`, pull typed responses
+     * via `next` (or `for await`), or `intoSplit` to separate the
+     * halves for the encoder-task / decoder-task pattern.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired through to
+     * the substrate's cancel-token primitive — same pattern as
+     * `callClientStream`. Aborting the signal drops both halves
+     * cleanly; the receive side observes EOF on its next pull and
+     * Drop emits CANCEL on the wire. `typedCall.close()` is still
+     * supported as the imperative cancel surface.
+     */
+    callDuplex<Req = unknown, Resp = unknown>(targetNodeId: bigint, service: string, opts?: CallOptions): Promise<TypedDuplexCall<Req, Resp>>;
+    /**
+     * Register a typed duplex handler. The user signature is
+     * `(stream: TypedRequestStream<Req>, sink: TypedResponseSink<Resp>) => Promise<void>`
+     * — the wrapper destructures the napi-side `[stream, sink]`
+     * tuple internally so the user handler never sees the array
+     * form. Handler return is `void`; the substrate emits the
+     * terminal frame automatically. To surface a typed Application
+     * status, throw `appError(code, body)` from the handler.
+     */
+    serveDuplex<Req = unknown, Resp = unknown>(service: string, handler: (stream: TypedRequestStream<Req>, sink: TypedResponseSink<Resp>) => Promise<void>): ServeHandle;
+    /**
+     * Install (pass a handler) or clear (pass `null`) the caller-side
+     * nRPC observer. The handler fires once per completed outbound
+     * RPC with a decoded {@link RpcCallEvent} — the tagged
+     * `status` discriminator is reconstructed from the napi POD's
+     * flat `statusKind` / `statusMessage` fields.
+     *
+     * **Callback contract (locked decision #1).** The handler fires
+     * synchronously from the substrate's dispatch path via a TSFN in
+     * `NonBlocking` mode — if the Node event loop is wedged, events
+     * are **dropped**, not buffered. Callbacks must therefore be
+     * cheap: push into a queue or ring buffer for slow consumers;
+     * do not do work inline. A bounded-mpsc + drop-counter layer is
+     * a deliberate post-v1 follow-up.
+     *
+     * **Mid-call swap.** The substrate uses `ArcSwap` for the
+     * observer slot, so swaps are atomic — but a swap mid-call
+     * means some events fire against the old handler, some against
+     * the new. Set the observer once at startup for clean
+     * semantics.
+     *
+     * v1 only emits `direction === 'outbound'` events; the
+     * server-side `'inbound'` hook is a planned follow-up.
+     */
+    setObserver(handler: ((evt: RpcCallEvent) => void) | null): void;
+    /**
+     * Snapshot the per-service nRPC metrics registry. Cheap — one
+     * DashMap iteration on the substrate side. Safe to collect on
+     * every Prometheus scrape. The returned object is a plain POD
+     * (no class wrapping); read fields directly or feed into your
+     * own exporter.
+     */
+    metricsSnapshot(): RpcMetricsSnapshot;
     /**
      * Direct-addressed typed call with retry. See {@link RetryPolicy}.
      */
@@ -167,6 +484,232 @@ export declare class TypedRpcStream<Resp = unknown> implements AsyncIterable<Res
     /** Close the stream; emits CANCEL to the server. Idempotent. */
     close(): Promise<void>;
 }
+/**
+ * Typed client-streaming call handle. Push typed requests via
+ * `send`, then await the terminal response with `finish`. Drop
+ * / `close` fires CANCEL via the underlying raw call's drop.
+ */
+export declare class TypedClientStreamCall<Req = unknown, Resp = unknown> {
+    private readonly _raw;
+    private readonly _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or on call resolution
+     * via `finish()`) so the AbortSignal listener doesn't outlive
+     * the call.
+     */
+    constructor(rawCall: RawClientStreamCall, detachSignal?: () => void);
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw(): RawClientStreamCall;
+    /**
+     * Encode `value` as JSON and push it as one request chunk.
+     * Throws `nrpc:codec_encode:` if encoding fails (the chunk is
+     * NOT sent in that case).
+     */
+    send(value: Req): Promise<void>;
+    /**
+     * Close the upload direction and await the terminal response.
+     * Consumes the call — subsequent `send` / `finish` throw
+     * `stream_closed`. Decode failure on the terminal Buffer
+     * surfaces as `nrpc:codec_decode:`.
+     */
+    finish(): Promise<Resp>;
+    /** Server-assigned `call_id`. */
+    callId(): Promise<bigint>;
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    flowControlled(): Promise<boolean>;
+    /**
+     * Close without finishing. Fires CANCEL on the wire if the
+     * initial REQUEST has flown. Idempotent. A concurrent in-flight
+     * `send()` awaiting flow-control credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callClientStream(opts.signal)`) so the
+     * signal can be reused for a subsequent call.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Typed inbound request stream surfaced to client-streaming +
+ * duplex server handlers. Drain via `next()` until it returns
+ * `null` (clean EOF) or implements `AsyncIterable<Req>` for
+ * `for await (const req of stream)` style.
+ *
+ * Decode failure on a chunk surfaces as `nrpc:codec_decode:` —
+ * the handler may catch and skip, or let it propagate to abort
+ * the call. The underlying raw stream is closed on decode
+ * failure so subsequent `next()` returns `null`.
+ */
+export declare class TypedRequestStream<Req = unknown> implements AsyncIterable<Req> {
+    private readonly _raw;
+    private _done;
+    constructor(rawStream: RawRequestStream);
+    /** Underlying raw stream for users who need the Buffer-level surface. */
+    get raw(): RawRequestStream;
+    /** Caller's peer origin hash (`0n` on the loopback fast path). */
+    get callerOrigin(): bigint;
+    /** Server-assigned `call_id`. */
+    get callId(): bigint;
+    /**
+     * Caller's declared deadline as a Unix-nanoseconds absolute
+     * timestamp. `0n` means no deadline was declared.
+     */
+    get deadlineNs(): bigint;
+    /**
+     * Initial-REQUEST headers carried by the caller. Each entry is
+     * `[name, value]` with `name` lowercase.
+     */
+    get headers(): [string, Buffer][];
+    /**
+     * Pull the next decoded request. Returns `null` on clean EOF.
+     * Throws `nrpc:codec_decode:` on decode failure (the underlying
+     * raw stream is marked closed; subsequent `next()` returns
+     * `null`).
+     */
+    next(): Promise<Req | null>;
+    /** Async iterator support: `for await (const req of stream) { ... }`. */
+    [Symbol.asyncIterator](): AsyncIterator<Req>;
+}
+/**
+ * Typed duplex call handle. Push typed requests via `send`,
+ * pull typed responses via `next` or `for await`, or call
+ * `intoSplit` to peel off independent sink + stream halves.
+ *
+ * After `intoSplit` returns, this call is "consumed" — calling
+ * `send` / `finishSending` / `next` / `close` on it throws.
+ */
+export declare class TypedDuplexCall<Req = unknown, Resp = unknown> implements AsyncIterable<Resp> {
+    private readonly _raw;
+    private _done;
+    private readonly _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or transferred to one
+     * of the split halves on `intoSplit`) so the AbortSignal
+     * listener doesn't outlive the call.
+     */
+    constructor(rawCall: RawDuplexCall, detachSignal?: () => void);
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw(): RawDuplexCall;
+    /** Encode + push one request chunk. */
+    send(value: Req): Promise<void>;
+    /** Close the upload direction (emit REQUEST_END). */
+    finishSending(): Promise<void>;
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying duplex call — subsequent `next()` returns `null`.
+     */
+    next(): Promise<Resp | null>;
+    /** Async iterator support over the response stream. */
+    [Symbol.asyncIterator](): AsyncIterator<Resp>;
+    /**
+     * Split the duplex into independent typed sink + stream halves.
+     * After return, this `TypedDuplexCall` is consumed — subsequent
+     * `send` / `finishSending` / `next` throw `stream_closed`.
+     * CANCEL fires only when BOTH split halves drop without
+     * observing the response stream's terminal frame.
+     *
+     * The AbortSignal listener (if one was wired) transfers to the
+     * sink half — the sink is the half that issues the upload,
+     * which is typically dropped first. Wherever the listener
+     * ends up, it stays attached until that half's `close()` runs;
+     * the stream half can still observe cancel-mid-flight via the
+     * substrate's cancel-token primitive even if the sink half's
+     * listener has already detached.
+     */
+    intoSplit(): Promise<[
+        TypedDuplexSink<Req>,
+        TypedDuplexStream<Resp>
+    ]>;
+    /** Server-assigned `call_id`. */
+    callId(): Promise<bigint>;
+    /**
+     * `true` if the call was opened with non-`None`
+     * `requestWindowInitial`. Reports the UPLOAD-direction
+     * flow-control state.
+     */
+    flowControlled(): Promise<boolean>;
+    /**
+     * Close without observing the response terminator. Fires
+     * CANCEL on the wire. Idempotent. Concurrent in-flight
+     * `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callDuplex(opts.signal)`) so the signal can
+     * be reused for a subsequent call.
+     */
+    close(): Promise<void>;
+}
+/** Send-half of a typed duplex call after `intoSplit`. */
+export declare class TypedDuplexSink<Req = unknown> {
+    private readonly _raw;
+    private readonly _detachSignal;
+    constructor(rawSink: RawDuplexSink, detachSignal?: () => void);
+    /** Underlying raw sink for Buffer-level access. */
+    get raw(): RawDuplexSink;
+    /** Encode + push one request chunk. */
+    send(value: Req): Promise<void>;
+    /** Close the upload direction (emit REQUEST_END). */
+    finish(): Promise<void>;
+    /** Server-assigned `call_id`. */
+    callId(): Promise<bigint>;
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    flowControlled(): Promise<boolean>;
+    /**
+     * Close without emitting REQUEST_END. Idempotent. Concurrent
+     * in-flight `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the AbortSignal listener (if one was transferred from
+     * the parent `TypedDuplexCall` via `intoSplit`).
+     */
+    close(): Promise<void>;
+}
+/** Receive-half of a typed duplex call after `intoSplit`. */
+export declare class TypedDuplexStream<Resp = unknown> implements AsyncIterable<Resp> {
+    private readonly _raw;
+    private _done;
+    constructor(rawStream: RawDuplexStream);
+    /** Underlying raw stream for Buffer-level access. */
+    get raw(): RawDuplexStream;
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying stream.
+     */
+    next(): Promise<Resp | null>;
+    /** Async iterator support over the response stream. */
+    [Symbol.asyncIterator](): AsyncIterator<Resp>;
+    /** Server-assigned `call_id`. */
+    callId(): Promise<bigint>;
+    /** Close the stream. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Typed outbound response sink for duplex server handlers.
+ * Non-async — mirrors `RawResponseSink.send`. Returns `true`
+ * when the chunk was enqueued; `false` if the underlying sink
+ * is closed. Encode failure throws `nrpc:codec_encode:` and the
+ * chunk is NOT sent.
+ *
+ * Flow control: the underlying sink `try_send`s into a bounded
+ * 1024-chunk mpsc; bursts past the credit window are dropped
+ * (counted by `streaming_chunks_dropped_total`). Pace your
+ * `send` calls via REQUEST_GRANT cadence for lossless flow
+ * control.
+ */
+export declare class TypedResponseSink<Resp = unknown> {
+    private readonly _raw;
+    constructor(rawSink: RawResponseSink);
+    /** Underlying raw sink for Buffer-level access. */
+    get raw(): RawResponseSink;
+    /**
+     * Encode + emit one response chunk. Returns `true` on
+     * successful enqueue; `false` if the sink has been closed.
+     * Throws `nrpc:codec_encode:` on encoding failure.
+     */
+    send(value: Resp): boolean;
+}
 export declare function defaultRetryable(err: unknown): boolean;
 export interface RetryPolicyOptions {
     /** Total attempts (NOT additional retries). Default 3. Must be >= 1. */
@@ -295,3 +838,11 @@ export declare function appError(code: number, body: string | Buffer): Error;
 export declare const NRPC_TYPED_BAD_REQUEST: 32768;
 /** RpcStatus::Application(0x8001): typed handler returned `throw`. */
 export declare const NRPC_TYPED_HANDLER_ERROR: 32769;
+/**
+ * Convert the napi POD shape (`RawRpcCallEvent` with flat
+ * `statusKind` / `statusMessage` fields) into the TS-idiomatic
+ * tagged `RpcCallEvent`. Exported for tests that need to
+ * synthesize observer events; production code receives already-
+ * decoded events via `TypedMeshRpc.setObserver`.
+ */
+export declare function rawEventToTyped(raw: RawRpcCallEvent): RpcCallEvent;

package/mesh_rpc.js

@@ -21,10 +21,28 @@
 //   const policy = new RetryPolicy({ maxAttempts: 3 })
 //   const reply = await rpc.callWithRetry(targetId, 'echo', req, undefined, policy)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NRPC_TYPED_HANDLER_ERROR = exports.NRPC_TYPED_BAD_REQUEST = exports.CircuitBreaker = exports.BreakerOpenError = exports.HedgePolicy = exports.RetryPolicy = exports.TypedRpcStream = exports.TypedMeshRpc = void 0;
+exports.NRPC_TYPED_HANDLER_ERROR = exports.NRPC_TYPED_BAD_REQUEST = exports.CircuitBreaker = exports.BreakerOpenError = exports.HedgePolicy = exports.RetryPolicy = exports.TypedResponseSink = exports.TypedDuplexStream = exports.TypedDuplexSink = exports.TypedDuplexCall = exports.TypedRequestStream = exports.TypedClientStreamCall = exports.TypedRpcStream = exports.TypedMeshRpc = exports.DIRECTION_INBOUND = exports.DIRECTION_OUTBOUND = exports.STATUS_KIND_CANCELED = exports.STATUS_KIND_TIMEOUT = exports.STATUS_KIND_ERROR = exports.STATUS_KIND_OK = void 0;
 exports.defaultRetryable = defaultRetryable;
 exports.defaultBreakerFailure = defaultBreakerFailure;
 exports.appError = appError;
+exports.rawEventToTyped = rawEventToTyped;
+/**
+ * Status-kind discriminants emitted on `RawRpcCallEvent.statusKind`
+ * and consumed when normalizing into the tagged-union
+ * {@link RpcCallStatus}. Prefer these constants over hard-coding
+ * the string literal in `if (evt.statusKind === '...')` checks —
+ * a typo on the literal silently never fires.
+ *
+ * Named `STATUS_KIND_*` to disambiguate from the wire-level
+ * `STATUS_*` u16 status codes used by `RpcServerError`.
+ */
+exports.STATUS_KIND_OK = 'ok';
+exports.STATUS_KIND_ERROR = 'error';
+exports.STATUS_KIND_TIMEOUT = 'timeout';
+exports.STATUS_KIND_CANCELED = 'canceled';
+/** Direction-kind discriminants on `RawRpcCallEvent.direction`. */
+exports.DIRECTION_OUTBOUND = 'outbound';
+exports.DIRECTION_INBOUND = 'inbound';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const native = require('./index');
 // Duck-typed message extractor — keeps the "any rejected value
@@ -172,6 +190,147 @@ class TypedMeshRpc {
     findServiceNodes(service) {
         return this._raw.findServiceNodes(service);
     }
+    // ---- client-streaming (S2-B1) -------------------------------------------
+    /**
+     * Open a typed client-streaming call. Returns a
+     * `TypedClientStreamCall<Req, Resp>` — push each request via
+     * `send(value)`, then `finish()` to drain the terminal
+     * response.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired end-to-end
+     * via the same `wireAbortSignal` helper unary calls use.
+     * `signal.aborted` triggers the substrate's
+     * `MeshNode::cancel(token)`, which drops the pending
+     * client-stream entry — the next `send()` / `finish()` observes
+     * a stream-closed error within bounded time, and the call's
+     * Drop emits CANCEL on the wire. Invoking `typedCall.close()`
+     * explicitly is still supported as the imperative cancel
+     * surface.
+     */
+    async callClientStream(targetNodeId, service, opts) {
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const rawCall = await this._raw.callClientStream(targetNodeId, service, rawOpts);
+            return new TypedClientStreamCall(rawCall, detach);
+        }
+        catch (err) {
+            detach();
+            throw err;
+        }
+    }
+    /**
+     * Register a typed client-streaming handler. The handler
+     * receives a `TypedRequestStream<Req>` (auto-decodes each
+     * inbound chunk to `Req`) and returns the terminal response
+     * `Resp` (encoded back to JSON before reaching the caller).
+     *
+     * Decode failure on a chunk surfaces from `stream.next()` as
+     * `nrpc:codec_decode:` — the handler may catch it (e.g. skip
+     * the bad chunk) or let it propagate. Letting it propagate
+     * surfaces to the caller as `RpcServerError(Internal)`; the
+     * handler may instead wrap it with `appError(NRPC_TYPED_BAD_REQUEST,
+     * ...)` to signal a typed bad-request status code.
+     */
+    serveClientStream(service, handler) {
+        return this._raw.serveClientStream(service, async (rawStream) => {
+            const typedStream = new TypedRequestStream(rawStream);
+            const resp = await handler(typedStream);
+            return jsonEncode(resp);
+        });
+    }
+    // ---- duplex (S2-B2) ----------------------------------------------------
+    /**
+     * Open a typed duplex call. Returns a `TypedDuplexCall<Req,
+     * Resp>` — push typed requests via `send`, pull typed responses
+     * via `next` (or `for await`), or `intoSplit` to separate the
+     * halves for the encoder-task / decoder-task pattern.
+     *
+     * Cancellation (v3 / C-A1): `opts.signal` is wired through to
+     * the substrate's cancel-token primitive — same pattern as
+     * `callClientStream`. Aborting the signal drops both halves
+     * cleanly; the receive side observes EOF on its next pull and
+     * Drop emits CANCEL on the wire. `typedCall.close()` is still
+     * supported as the imperative cancel surface.
+     */
+    async callDuplex(targetNodeId, service, opts) {
+        const { rawOpts, detach } = wireAbortSignal(this._raw, opts);
+        try {
+            const rawCall = await this._raw.callDuplex(targetNodeId, service, rawOpts);
+            return new TypedDuplexCall(rawCall, detach);
+        }
+        catch (err) {
+            detach();
+            throw err;
+        }
+    }
+    /**
+     * Register a typed duplex handler. The user signature is
+     * `(stream: TypedRequestStream<Req>, sink: TypedResponseSink<Resp>) => Promise<void>`
+     * — the wrapper destructures the napi-side `[stream, sink]`
+     * tuple internally so the user handler never sees the array
+     * form. Handler return is `void`; the substrate emits the
+     * terminal frame automatically. To surface a typed Application
+     * status, throw `appError(code, body)` from the handler.
+     */
+    serveDuplex(service, handler) {
+        return this._raw.serveDuplex(service, async ([rawStream, rawSink]) => {
+            const typedStream = new TypedRequestStream(rawStream);
+            const typedSink = new TypedResponseSink(rawSink);
+            await handler(typedStream, typedSink);
+            // The napi side discards the terminal Buffer for duplex
+            // handlers (only the Ok/Err outcome matters — see
+            // NodeDuplexRpcHandler at bindings/node/src/mesh_rpc.rs).
+            // Return an empty Buffer so the JS signature is satisfied.
+            return DUPLEX_TERMINAL_SENTINEL;
+        });
+    }
+    // ---- observer + metrics (S2-B3) ----------------------------------------
+    /**
+     * Install (pass a handler) or clear (pass `null`) the caller-side
+     * nRPC observer. The handler fires once per completed outbound
+     * RPC with a decoded {@link RpcCallEvent} — the tagged
+     * `status` discriminator is reconstructed from the napi POD's
+     * flat `statusKind` / `statusMessage` fields.
+     *
+     * **Callback contract (locked decision #1).** The handler fires
+     * synchronously from the substrate's dispatch path via a TSFN in
+     * `NonBlocking` mode — if the Node event loop is wedged, events
+     * are **dropped**, not buffered. Callbacks must therefore be
+     * cheap: push into a queue or ring buffer for slow consumers;
+     * do not do work inline. A bounded-mpsc + drop-counter layer is
+     * a deliberate post-v1 follow-up.
+     *
+     * **Mid-call swap.** The substrate uses `ArcSwap` for the
+     * observer slot, so swaps are atomic — but a swap mid-call
+     * means some events fire against the old handler, some against
+     * the new. Set the observer once at startup for clean
+     * semantics.
+     *
+     * v1 only emits `direction === 'outbound'` events; the
+     * server-side `'inbound'` hook is a planned follow-up.
+     */
+    setObserver(handler) {
+        if (handler === null) {
+            this._raw.setObserver(null);
+            return;
+        }
+        // Normalize the napi POD's flat `statusKind` / `statusMessage`
+        // into the TS-idiomatic tagged `RpcCallStatus` discriminator
+        // before reaching user code.
+        this._raw.setObserver((raw) => {
+            handler(rawEventToTyped(raw));
+        });
+    }
+    /**
+     * Snapshot the per-service nRPC metrics registry. Cheap — one
+     * DashMap iteration on the substrate side. Safe to collect on
+     * every Prometheus scrape. The returned object is a plain POD
+     * (no class wrapping); read fields directly or feed into your
+     * own exporter.
+     */
+    metricsSnapshot() {
+        return this._raw.metricsSnapshot();
+    }
     // ---- resilience helpers --------------------------------------------------
     /**
      * Direct-addressed typed call with retry. See {@link RetryPolicy}.
@@ -277,6 +436,486 @@ class TypedRpcStream {
 }
 exports.TypedRpcStream = TypedRpcStream;
 // ============================================================================
+// TypedClientStreamCall + TypedRequestStream (S2-B1).
+//
+// Client-streaming: caller pushes typed Reqs via `send`, then
+// `finish` awaits a single terminal Resp.
+//
+// Server-side handler shape mirrors the unary `serve`'s decode
+// boundary — chunks decode lazily inside `TypedRequestStream.next`
+// so a single malformed chunk doesn't poison the entire stream
+// (the handler can catch and skip).
+//
+// Cancellation contract (locked decision #2): v1 supports
+// `close()`-only cancellation. AbortSignal / cancel-token wiring
+// across streaming shapes is a deliberate post-v1 follow-up.
+// ============================================================================
+/**
+ * Typed client-streaming call handle. Push typed requests via
+ * `send`, then await the terminal response with `finish`. Drop
+ * / `close` fires CANCEL via the underlying raw call's drop.
+ */
+class TypedClientStreamCall {
+    _raw;
+    _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or on call resolution
+     * via `finish()`) so the AbortSignal listener doesn't outlive
+     * the call.
+     */
+    constructor(rawCall, detachSignal = () => { }) {
+        this._raw = rawCall;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Encode `value` as JSON and push it as one request chunk.
+     * Throws `nrpc:codec_encode:` if encoding fails (the chunk is
+     * NOT sent in that case).
+     */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /**
+     * Close the upload direction and await the terminal response.
+     * Consumes the call — subsequent `send` / `finish` throw
+     * `stream_closed`. Decode failure on the terminal Buffer
+     * surfaces as `nrpc:codec_decode:`.
+     */
+    async finish() {
+        try {
+            const buf = await this._raw.finish();
+            return jsonDecode(buf);
+        }
+        finally {
+            this._detachSignal();
+        }
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without finishing. Fires CANCEL on the wire if the
+     * initial REQUEST has flown. Idempotent. A concurrent in-flight
+     * `send()` awaiting flow-control credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callClientStream(opts.signal)`) so the
+     * signal can be reused for a subsequent call.
+     */
+    async close() {
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedClientStreamCall = TypedClientStreamCall;
+/**
+ * Typed inbound request stream surfaced to client-streaming +
+ * duplex server handlers. Drain via `next()` until it returns
+ * `null` (clean EOF) or implements `AsyncIterable<Req>` for
+ * `for await (const req of stream)` style.
+ *
+ * Decode failure on a chunk surfaces as `nrpc:codec_decode:` —
+ * the handler may catch and skip, or let it propagate to abort
+ * the call. The underlying raw stream is closed on decode
+ * failure so subsequent `next()` returns `null`.
+ */
+class TypedRequestStream {
+    _raw;
+    _done;
+    constructor(rawStream) {
+        this._raw = rawStream;
+        this._done = false;
+    }
+    /** Underlying raw stream for users who need the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /** Caller's peer origin hash (`0n` on the loopback fast path). */
+    get callerOrigin() {
+        return this._raw.callerOrigin;
+    }
+    /** Server-assigned `call_id`. */
+    get callId() {
+        return this._raw.callId;
+    }
+    /**
+     * Caller's declared deadline as a Unix-nanoseconds absolute
+     * timestamp. `0n` means no deadline was declared.
+     */
+    get deadlineNs() {
+        return this._raw.deadlineNs;
+    }
+    /**
+     * Initial-REQUEST headers carried by the caller. Each entry is
+     * `[name, value]` with `name` lowercase.
+     */
+    get headers() {
+        return this._raw.headers;
+    }
+    /**
+     * Pull the next decoded request. Returns `null` on clean EOF.
+     * Throws `nrpc:codec_decode:` on decode failure (the underlying
+     * raw stream is marked closed; subsequent `next()` returns
+     * `null`).
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            // Mark done so subsequent next() returns null — refuse to
+            // continue draining a stream whose framing is broken.
+            this._done = true;
+            throw e;
+        }
+    }
+    /** Async iterator support: `for await (const req of stream) { ... }`. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+}
+exports.TypedRequestStream = TypedRequestStream;
+// ============================================================================
+// TypedDuplexCall + TypedDuplexSink + TypedDuplexStream +
+// TypedResponseSink (S2-B2).
+//
+// Duplex: caller pushes Reqs and pulls Resps concurrently on a
+// single call. `intoSplit` separates the halves for the encoder-
+// task / decoder-task pattern where each half lives in its own
+// async task.
+//
+// Cancellation contract (locked decision #2): v1 `.close()`-only,
+// same as client-streaming.
+// ============================================================================
+/**
+ * Constant sentinel returned by the duplex serve-handler shim.
+ * The napi `NodeDuplexRpcHandler` discards the terminal Buffer
+ * (only the Ok/Err outcome matters for duplex), so a stable
+ * empty Buffer is enough.
+ */
+const DUPLEX_TERMINAL_SENTINEL = Buffer.alloc(0);
+/**
+ * Typed duplex call handle. Push typed requests via `send`,
+ * pull typed responses via `next` or `for await`, or call
+ * `intoSplit` to peel off independent sink + stream halves.
+ *
+ * After `intoSplit` returns, this call is "consumed" — calling
+ * `send` / `finishSending` / `next` / `close` on it throws.
+ */
+class TypedDuplexCall {
+    _raw;
+    _done;
+    _detachSignal;
+    /**
+     * `detachSignal` is the cleanup function returned by
+     * `wireAbortSignal`. Run on `close()` (or transferred to one
+     * of the split halves on `intoSplit`) so the AbortSignal
+     * listener doesn't outlive the call.
+     */
+    constructor(rawCall, detachSignal = () => { }) {
+        this._raw = rawCall;
+        this._done = false;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw call for users who want the Buffer-level surface. */
+    get raw() {
+        return this._raw;
+    }
+    /** Encode + push one request chunk. */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /** Close the upload direction (emit REQUEST_END). */
+    async finishSending() {
+        await this._raw.finishSending();
+    }
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying duplex call — subsequent `next()` returns `null`.
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            this._done = true;
+            try {
+                await this._raw.close();
+            }
+            catch {
+                /* swallow — best-effort */
+            }
+            throw e;
+        }
+    }
+    /** Async iterator support over the response stream. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+    /**
+     * Split the duplex into independent typed sink + stream halves.
+     * After return, this `TypedDuplexCall` is consumed — subsequent
+     * `send` / `finishSending` / `next` throw `stream_closed`.
+     * CANCEL fires only when BOTH split halves drop without
+     * observing the response stream's terminal frame.
+     *
+     * The AbortSignal listener (if one was wired) transfers to the
+     * sink half — the sink is the half that issues the upload,
+     * which is typically dropped first. Wherever the listener
+     * ends up, it stays attached until that half's `close()` runs;
+     * the stream half can still observe cancel-mid-flight via the
+     * substrate's cancel-token primitive even if the sink half's
+     * listener has already detached.
+     */
+    async intoSplit() {
+        const [rawSink, rawStream] = await this._raw.intoSplit();
+        this._done = true;
+        return [
+            new TypedDuplexSink(rawSink, this._detachSignal),
+            new TypedDuplexStream(rawStream),
+        ];
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /**
+     * `true` if the call was opened with non-`None`
+     * `requestWindowInitial`. Reports the UPLOAD-direction
+     * flow-control state.
+     */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without observing the response terminator. Fires
+     * CANCEL on the wire. Idempotent. Concurrent in-flight
+     * `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the `AbortSignal` listener (if one was wired by
+     * `TypedMeshRpc.callDuplex(opts.signal)`) so the signal can
+     * be reused for a subsequent call.
+     */
+    async close() {
+        this._done = true;
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexCall = TypedDuplexCall;
+/** Send-half of a typed duplex call after `intoSplit`. */
+class TypedDuplexSink {
+    _raw;
+    _detachSignal;
+    constructor(rawSink, detachSignal = () => { }) {
+        this._raw = rawSink;
+        this._detachSignal = detachSignal;
+    }
+    /** Underlying raw sink for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /** Encode + push one request chunk. */
+    async send(value) {
+        const buf = jsonEncode(value);
+        await this._raw.send(buf);
+    }
+    /** Close the upload direction (emit REQUEST_END). */
+    async finish() {
+        await this._raw.finish();
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** `true` if the call was opened with `requestWindowInitial`. */
+    async flowControlled() {
+        return await this._raw.flowControlled();
+    }
+    /**
+     * Close without emitting REQUEST_END. Idempotent. Concurrent
+     * in-flight `send()` awaiting credit observes `stream_closed`.
+     *
+     * Detaches the AbortSignal listener (if one was transferred from
+     * the parent `TypedDuplexCall` via `intoSplit`).
+     */
+    async close() {
+        this._detachSignal();
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexSink = TypedDuplexSink;
+/** Receive-half of a typed duplex call after `intoSplit`. */
+class TypedDuplexStream {
+    _raw;
+    _done;
+    constructor(rawStream) {
+        this._raw = rawStream;
+        this._done = false;
+    }
+    /** Underlying raw stream for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Pull the next decoded response. Returns `null` on clean EOF.
+     * Decode failure throws `nrpc:codec_decode:` and closes the
+     * underlying stream.
+     */
+    async next() {
+        if (this._done)
+            return null;
+        let buf;
+        try {
+            buf = await this._raw.next();
+        }
+        catch (e) {
+            this._done = true;
+            throw e;
+        }
+        if (buf === null || buf === undefined) {
+            this._done = true;
+            return null;
+        }
+        try {
+            return jsonDecode(buf);
+        }
+        catch (e) {
+            this._done = true;
+            try {
+                await this._raw.close();
+            }
+            catch {
+                /* swallow — best-effort */
+            }
+            throw e;
+        }
+    }
+    /** Async iterator support over the response stream. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const value = await this.next();
+            if (value === null)
+                return;
+            yield value;
+        }
+    }
+    /** Server-assigned `call_id`. */
+    async callId() {
+        return await this._raw.callId();
+    }
+    /** Close the stream. Idempotent. */
+    async close() {
+        this._done = true;
+        try {
+            await this._raw.close();
+        }
+        catch {
+            /* swallow — best-effort */
+        }
+    }
+}
+exports.TypedDuplexStream = TypedDuplexStream;
+/**
+ * Typed outbound response sink for duplex server handlers.
+ * Non-async — mirrors `RawResponseSink.send`. Returns `true`
+ * when the chunk was enqueued; `false` if the underlying sink
+ * is closed. Encode failure throws `nrpc:codec_encode:` and the
+ * chunk is NOT sent.
+ *
+ * Flow control: the underlying sink `try_send`s into a bounded
+ * 1024-chunk mpsc; bursts past the credit window are dropped
+ * (counted by `streaming_chunks_dropped_total`). Pace your
+ * `send` calls via REQUEST_GRANT cadence for lossless flow
+ * control.
+ */
+class TypedResponseSink {
+    _raw;
+    constructor(rawSink) {
+        this._raw = rawSink;
+    }
+    /** Underlying raw sink for Buffer-level access. */
+    get raw() {
+        return this._raw;
+    }
+    /**
+     * Encode + emit one response chunk. Returns `true` on
+     * successful enqueue; `false` if the sink has been closed.
+     * Throws `nrpc:codec_encode:` on encoding failure.
+     */
+    send(value) {
+        const buf = jsonEncode(value);
+        return this._raw.send(buf);
+    }
+}
+exports.TypedResponseSink = TypedResponseSink;
+// ============================================================================
 // RetryPolicy — mirrors net_sdk::mesh_rpc_resilience::RetryPolicy.
 //
 // Defaults: 3 attempts, 50ms initial backoff, doubling per
@@ -783,3 +1422,38 @@ function appError(code, body) {
 exports.NRPC_TYPED_BAD_REQUEST = 0x8000;
 /** RpcStatus::Application(0x8001): typed handler returned `throw`. */
 exports.NRPC_TYPED_HANDLER_ERROR = 0x8001;
+/**
+ * Convert the napi POD shape (`RawRpcCallEvent` with flat
+ * `statusKind` / `statusMessage` fields) into the TS-idiomatic
+ * tagged `RpcCallEvent`. Exported for tests that need to
+ * synthesize observer events; production code receives already-
+ * decoded events via `TypedMeshRpc.setObserver`.
+ */
+function rawEventToTyped(raw) {
+    let status;
+    switch (raw.statusKind) {
+        case exports.STATUS_KIND_OK:
+            status = { kind: 'ok' };
+            break;
+        case exports.STATUS_KIND_ERROR:
+            status = { kind: 'error', message: raw.statusMessage ?? '' };
+            break;
+        case exports.STATUS_KIND_TIMEOUT:
+            status = { kind: 'timeout' };
+            break;
+        case exports.STATUS_KIND_CANCELED:
+            status = { kind: 'canceled' };
+            break;
+    }
+    return {
+        caller: raw.caller,
+        callee: raw.callee,
+        method: raw.method,
+        latencyMs: raw.latencyMs,
+        status,
+        requestBytes: raw.requestBytes,
+        responseBytes: raw.responseBytes,
+        direction: raw.direction,
+        tsUnixMs: raw.tsUnixMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/core",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "High-performance, schema-agnostic event bus for AI runtime workloads",
   "main": "index.js",
   "types": "index.d.ts",
@@ -91,13 +91,13 @@
     "node": ">=20"
   },
   "optionalDependencies": {
-    "@net-mesh/core-win32-x64-msvc": "0.22.0",
-    "@net-mesh/core-win32-arm64-msvc": "0.22.0",
-    "@net-mesh/core-darwin-x64": "0.22.0",
-    "@net-mesh/core-darwin-arm64": "0.22.0",
-    "@net-mesh/core-linux-x64-gnu": "0.22.0",
-    "@net-mesh/core-linux-x64-musl": "0.22.0",
-    "@net-mesh/core-linux-arm64-gnu": "0.22.0",
-    "@net-mesh/core-linux-arm64-musl": "0.22.0"
+    "@net-mesh/core-win32-x64-msvc": "0.24.0",
+    "@net-mesh/core-win32-arm64-msvc": "0.24.0",
+    "@net-mesh/core-darwin-x64": "0.24.0",
+    "@net-mesh/core-darwin-arm64": "0.24.0",
+    "@net-mesh/core-linux-x64-gnu": "0.24.0",
+    "@net-mesh/core-linux-x64-musl": "0.24.0",
+    "@net-mesh/core-linux-arm64-gnu": "0.24.0",
+    "@net-mesh/core-linux-arm64-musl": "0.24.0"
   }
 }