@net-mesh/core 0.21.0 → 0.23.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;