@net-mesh/core 0.19.0

package/README.md

@@ -0,0 +1,45 @@
+# @net-mesh/core
+
+napi-rs binding to the `libnet` cdylib — the Node-facing surface for the Net mesh, RedEX, CortEX, NetDB, MeshDB, and MeshOS.
+
+## Install
+
+```bash
+npm install @net-mesh/core
+```
+
+The package publishes pre-built `.node` artifacts for every platform listed in `package.json -> napi.targets`. Pulling the package from npm requires no Rust toolchain.
+
+## Build from source
+
+```bash
+npm install
+npm run build          # release; full feature set
+npm run build:debug    # debug; full feature set
+```
+
+The canonical feature list lives in `package.json -> scripts.build` so CI artifacts and local builds stay aligned.
+
+## Cargo features
+
+The five feature flags that gate the storage / query / OS surfaces on this binding. Artifacts published to npm ship with every feature enabled; `napi build` invocations without a feature silently omit its symbols and the build never warns. The TypeScript wrapper destructures the napi exports lazily, so a missing feature surfaces as `undefined` at the import site rather than a load-time error.
+
+| Feature | Surface enabled in the napi module |
+|---|---|
+| `cortex` | `Redex`, `RedexFile`, `TasksAdapter`, `MemoriesAdapter`, `NetDb`, `Task`, `Memory`, watch iterators, `RedexError`, `CortexError`, `NetDbError` |
+| `redex-disk` | Disk-backed RedEX persistence — the `persistentDir` ctor option and `persistent: true` on `openFile`. Without it the persistent path rejects with `RedexError`. |
+| `netdb` | `NetDb` composition (requires `cortex`); the `net_netdb_*` FFI entry points ship with this feature. |
+| `meshdb` | `MeshQuery`, `MeshQueryRunner`, `QueryBuilder`, `Predicate`, `InMemoryChainReader`, plus the `libnet_meshdb` cdylib. |
+| `meshos` | `MeshOsDaemonSdk`, `MeshOsDaemonHandle`, plus the `libnet_meshos` cdylib. |
+
+Enable at build time:
+
+```bash
+napi build --platform --release --features "cortex netdb redex-disk meshdb meshos"
+```
+
+The repo's `npm run build` script already passes a superset of these flags (`redis,net,cortex,compute,groups,meshos,deck,meshdb`) — see `package.json -> scripts.build` for the exact invocation. Slim the list by editing that script or invoking `napi build` directly with the features you actually need.
+
+## License
+
+Apache-2.0

package/errors.d.ts

@@ -0,0 +1,62 @@
+export declare class CortexError extends Error {
+    constructor(detail?: string);
+}
+export declare class NetDbError extends Error {
+    constructor(detail?: string);
+}
+export declare class RpcError extends Error {
+    constructor(detail?: string);
+}
+export declare class RpcNoRouteError extends RpcError {
+    constructor(detail?: string);
+}
+export declare class RpcTimeoutError extends RpcError {
+    /** Caller-side elapsed time, parsed out of `elapsed_ms=N` in the message. */
+    readonly elapsedMs?: number;
+    constructor(detail?: string);
+}
+export declare class RpcServerError extends RpcError {
+    /** Wire-level RpcStatus parsed out of `status=0xNNNN` in the message. */
+    readonly status?: number;
+    constructor(detail?: string);
+}
+export declare class RpcTransportError extends RpcError {
+    constructor(detail?: string);
+}
+export declare class RpcCodecError extends RpcError {
+    /** Which side of the call surfaced the codec failure. */
+    readonly direction?: 'encode' | 'decode';
+    constructor(detail?: string, direction?: 'encode' | 'decode');
+}
+/**
+ * Caller-driven cancellation. Raised when an in-flight unary
+ * call is aborted via `MeshRpc.cancelCall(token)` or via an
+ * AbortSignal attached through the typed wrapper's `opts.signal`.
+ * CANCEL has been published to the server; the server-side
+ * handler observes its `ctx.cancellation` token. Caller-fixable
+ * / terminal — NOT retried by the default retry policy.
+ */
+export declare class RpcCancelledError extends RpcError {
+    constructor(detail?: string);
+}
+/**
+ * Inspect an error's message prefix and return a typed error if it
+ * matches the napi binding's contract. Non-matching errors are
+ * returned unchanged — caller can `throw` the result unconditionally.
+ *
+ * Duck-typed on `e.message`: napi rejections are real Error
+ * instances, but top-level catch handlers may also see arbitrary
+ * non-Error values (a thrown string, a plain `{message}` object).
+ * We mirror the JS contract — accept anything with a string
+ * `message` field — so cross-runtime catch sites don't lose
+ * classification just because the throw happened in a context
+ * where `instanceof Error` is unreliable (vm boundaries, polyfills).
+ */
+export declare function classifyError(e: unknown): unknown;
+/**
+ * Pull a `message` field off any value, with the same permissive
+ * semantics as `(e && e.message) || ''` from the JS source. Used
+ * by `classifyError` and by `defaultRetryable` in
+ * `@net-mesh/core/mesh_rpc` to keep the catch-site contract uniform.
+ */
+export declare function extractMessage(e: unknown): string;

package/errors.js

@@ -0,0 +1,209 @@
+"use strict";
+// Typed error classes for CortEX / NetDB / nRPC operations.
+//
+// The napi binding throws plain `Error` objects with stable prefixes
+// (`cortex:` / `netdb:` / `nrpc:`) that `classifyError()` inspects to
+// re-throw a typed error. Catch with `instanceof`:
+//
+//   import { NetDb } from '@net-mesh/core';
+//   import { CortexError, classifyError } from '@net-mesh/core/errors';
+//
+//   try {
+//     db.tasks.create(1n, 'x', 100n);
+//   } catch (e) {
+//     throw classifyError(e); // CortexError / NetDbError / original
+//   }
+//
+// Prefixes mirror `ERR_*_PREFIX` in `bindings/node/src/cortex.rs`
+// and `bindings/node/src/mesh_rpc.rs`. Keep the strings in lockstep.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcCancelledError = exports.RpcCodecError = exports.RpcTransportError = exports.RpcServerError = exports.RpcTimeoutError = exports.RpcNoRouteError = exports.RpcError = exports.NetDbError = exports.CortexError = void 0;
+exports.classifyError = classifyError;
+exports.extractMessage = extractMessage;
+const ERR_CORTEX_PREFIX = 'cortex:';
+const ERR_NETDB_PREFIX = 'netdb:';
+const ERR_NRPC_PREFIX = 'nrpc:';
+class CortexError extends Error {
+    constructor(detail) {
+        super(detail ?? 'cortex adapter error');
+        this.name = 'CortexError';
+        Object.setPrototypeOf(this, CortexError.prototype);
+    }
+}
+exports.CortexError = CortexError;
+class NetDbError extends Error {
+    constructor(detail) {
+        super(detail ?? 'netdb error');
+        this.name = 'NetDbError';
+        Object.setPrototypeOf(this, NetDbError.prototype);
+    }
+}
+exports.NetDbError = NetDbError;
+// nRPC error hierarchy. Mirrors net::adapter::net::mesh_rpc::RpcError;
+// the napi binding's mesh_rpc.rs::nrpc_err_from_inner emits each
+// variant under a stable kind segment after the `nrpc:` prefix:
+//
+//   nrpc:no_route       -> RpcNoRouteError
+//   nrpc:timeout        -> RpcTimeoutError
+//   nrpc:server_error   -> RpcServerError
+//   nrpc:transport      -> RpcTransportError
+//   nrpc:codec_encode   -> RpcCodecError(direction='encode')
+//   nrpc:codec_decode   -> RpcCodecError(direction='decode')
+//   nrpc:cancelled      -> RpcCancelledError
+//   nrpc:* (anything else) -> RpcError (the base class)
+//
+// Catch with `instanceof RpcError` for "any nRPC failure", or
+// drill down to a concrete subclass for specific handling. The
+// default retry / circuit-breaker policies in @net-mesh/core/mesh_rpc
+// skip RpcCodecError (caller-fixable local bug) by default — same
+// behavior as the Rust SDK's default_retryable predicate.
+class RpcError extends Error {
+    constructor(detail) {
+        super(detail ?? 'rpc error');
+        this.name = 'RpcError';
+        Object.setPrototypeOf(this, RpcError.prototype);
+    }
+}
+exports.RpcError = RpcError;
+class RpcNoRouteError extends RpcError {
+    constructor(detail) {
+        super(detail ?? 'no route to target');
+        this.name = 'RpcNoRouteError';
+        Object.setPrototypeOf(this, RpcNoRouteError.prototype);
+    }
+}
+exports.RpcNoRouteError = RpcNoRouteError;
+class RpcTimeoutError extends RpcError {
+    constructor(detail) {
+        super(detail ?? 'rpc timeout');
+        this.name = 'RpcTimeoutError';
+        Object.setPrototypeOf(this, RpcTimeoutError.prototype);
+        // Best-effort parse of `elapsed_ms=N` so callers can read
+        // `err.elapsedMs` without re-parsing the message.
+        const m = /elapsed_ms=(\d+)/.exec(detail ?? '');
+        if (m)
+            this.elapsedMs = Number(m[1]);
+    }
+}
+exports.RpcTimeoutError = RpcTimeoutError;
+class RpcServerError extends RpcError {
+    constructor(detail) {
+        super(detail ?? 'rpc server error');
+        this.name = 'RpcServerError';
+        Object.setPrototypeOf(this, RpcServerError.prototype);
+        // Parse `status=0xNNNN` so callers can pattern-match by
+        // status code (e.g. err.status === 0x8001 → typed-handler
+        // application error).
+        const m = /status=0x([0-9a-fA-F]+)/.exec(detail ?? '');
+        if (m)
+            this.status = parseInt(m[1], 16);
+    }
+}
+exports.RpcServerError = RpcServerError;
+class RpcTransportError extends RpcError {
+    constructor(detail) {
+        super(detail ?? 'rpc transport error');
+        this.name = 'RpcTransportError';
+        Object.setPrototypeOf(this, RpcTransportError.prototype);
+    }
+}
+exports.RpcTransportError = RpcTransportError;
+class RpcCodecError extends RpcError {
+    /** Which side of the call surfaced the codec failure. */
+    direction;
+    constructor(detail, direction) {
+        super(detail ?? 'rpc codec error');
+        this.name = 'RpcCodecError';
+        // `direction` is always passed through, so it's a regular
+        // assignment (no `declare`-dance needed — `'direction' in err`
+        // is `true` regardless of whether a specific value was provided).
+        this.direction = direction;
+        Object.setPrototypeOf(this, RpcCodecError.prototype);
+    }
+}
+exports.RpcCodecError = RpcCodecError;
+/**
+ * Caller-driven cancellation. Raised when an in-flight unary
+ * call is aborted via `MeshRpc.cancelCall(token)` or via an
+ * AbortSignal attached through the typed wrapper's `opts.signal`.
+ * CANCEL has been published to the server; the server-side
+ * handler observes its `ctx.cancellation` token. Caller-fixable
+ * / terminal — NOT retried by the default retry policy.
+ */
+class RpcCancelledError extends RpcError {
+    constructor(detail) {
+        super(detail ?? 'rpc cancelled');
+        this.name = 'RpcCancelledError';
+        Object.setPrototypeOf(this, RpcCancelledError.prototype);
+    }
+}
+exports.RpcCancelledError = RpcCancelledError;
+/**
+ * Inspect an error's message prefix and return a typed error if it
+ * matches the napi binding's contract. Non-matching errors are
+ * returned unchanged — caller can `throw` the result unconditionally.
+ *
+ * Duck-typed on `e.message`: napi rejections are real Error
+ * instances, but top-level catch handlers may also see arbitrary
+ * non-Error values (a thrown string, a plain `{message}` object).
+ * We mirror the JS contract — accept anything with a string
+ * `message` field — so cross-runtime catch sites don't lose
+ * classification just because the throw happened in a context
+ * where `instanceof Error` is unreliable (vm boundaries, polyfills).
+ */
+function classifyError(e) {
+    const msg = extractMessage(e);
+    if (msg.startsWith(ERR_CORTEX_PREFIX)) {
+        return new CortexError(msg);
+    }
+    if (msg.startsWith(ERR_NETDB_PREFIX)) {
+        return new NetDbError(msg);
+    }
+    if (msg.startsWith(ERR_NRPC_PREFIX)) {
+        return classifyRpcError(msg);
+    }
+    return e;
+}
+/**
+ * Pull a `message` field off any value, with the same permissive
+ * semantics as `(e && e.message) || ''` from the JS source. Used
+ * by `classifyError` and by `defaultRetryable` in
+ * `@net-mesh/core/mesh_rpc` to keep the catch-site contract uniform.
+ */
+function extractMessage(e) {
+    if (e === null || e === undefined)
+        return '';
+    if (typeof e === 'string')
+        return e;
+    if (typeof e !== 'object')
+        return '';
+    const msg = e.message;
+    return typeof msg === 'string' ? msg : '';
+}
+function classifyRpcError(msg) {
+    // Strip the `nrpc:` prefix; the next segment up to the first
+    // `:` is the kind. Examples:
+    //   nrpc:no_route: target=0x... reason=...
+    //   nrpc:codec_encode: client encode: ...
+    const after = msg.slice(ERR_NRPC_PREFIX.length);
+    const colonIdx = after.indexOf(':');
+    const kind = colonIdx === -1 ? after : after.slice(0, colonIdx);
+    switch (kind) {
+        case 'no_route':
+            return new RpcNoRouteError(msg);
+        case 'timeout':
+            return new RpcTimeoutError(msg);
+        case 'server_error':
+            return new RpcServerError(msg);
+        case 'transport':
+            return new RpcTransportError(msg);
+        case 'codec_encode':
+            return new RpcCodecError(msg, 'encode');
+        case 'codec_decode':
+            return new RpcCodecError(msg, 'decode');
+        case 'cancelled':
+            return new RpcCancelledError(msg);
+        default:
+            return new RpcError(msg);
+    }
+}

package/mesh_rpc.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Per-call options forwarded to the raw napi `MeshRpc`. Mirrors
+ * the napi `CallOptions` struct. Routing policy + trace context
+ * land in a later phase.
+ */
+export interface CallOptions {
+    /** Hard deadline, milliseconds from now. */
+    deadlineMs?: number;
+    /**
+     * Streaming-only: initial credit window for per-streaming-
+     * response flow control. `undefined` → unbounded.
+     */
+    streamWindowInitial?: number;
+    /**
+     * Caller-driven cancellation. Pass an `AbortSignal`; the typed
+     * wrapper attaches a one-shot listener that aborts the in-
+     * flight call. The call rejects with `RpcCancelledError`.
+     * Recognized by `TypedMeshRpc` only — the raw napi `MeshRpc`
+     * uses `cancelToken` directly.
+     */
+    signal?: AbortSignal;
+    /**
+     * Raw cancel token (advanced; usually set automatically by the
+     * typed wrapper from `signal`). Mint via
+     * `MeshRpc.reserveCancelToken()` and pair with
+     * `MeshRpc.cancelCall(token)`. Most users should use `signal`
+     * instead.
+     */
+    cancelToken?: bigint;
+    /**
+     * Caller-supplied request headers, appended to the wire
+     * `RpcRequestPayload.headers`. Used for application-level metadata
+     * the server needs at dispatch-time — most notably the
+     * `net-where:` predicate header for Phase 9b
+     * predicate-pushdown filtering.
+     *
+     * Convenience: build entries via `whereHeader(pred)` from
+     * `@net-mesh/sdk` for predicate-pushdown.
+     */
+    requestHeaders?: RpcRequestHeader[];
+}
+/**
+ * Single request-header entry. Names follow the lowercase
+ * `cyberdeck-*` / `nrpc-*` convention.
+ */
+export interface RpcRequestHeader {
+    name: string;
+    /**
+     * Header value bytes. For text-like headers (predicates,
+     * trace-context), encode with `Buffer.from(str)`.
+     */
+    value: Buffer;
+}
+/**
+ * Handle returned by {@link TypedMeshRpc.serve}. Calling `close()`
+ * unregisters the service; in-flight handlers continue to
+ * completion. Always call `close()` explicitly when done — V8 GC
+ * eventually finalizes the underlying napi class but timing is
+ * non-deterministic.
+ */
+export interface ServeHandle {
+    close(): void;
+    isClosed(): boolean;
+}
+/**
+ * Raw napi `MeshRpc` shape. Test stubs and the runtime-loaded
+ * `native.MeshRpc` instance both conform to this interface. Used
+ * as the `TypedMeshRpc` constructor parameter type.
+ */
+export interface RawMeshRpc {
+    serve(service: string, handler: (req: Buffer) => Promise<Buffer>): ServeHandle;
+    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>;
+    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;
+}
+/** Raw napi `RpcStream` — minimal shape consumed by `TypedRpcStream`. */
+export interface RawRpcStream {
+    next(): Promise<Buffer | null>;
+    grant(n: number): Promise<void>;
+    flowControlled(): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** Handler signature: receives the decoded request and returns a response. */
+export type TypedHandler<Req = unknown, Resp = unknown> = (req: Req) => Resp | Promise<Resp>;
+export declare class TypedMeshRpc {
+    private readonly _raw;
+    /**
+     * Build a TypedMeshRpc against a NetMesh. Cheap; returns a
+     * new wrapper around an internal raw MeshRpc.
+     */
+    static fromMesh(mesh: object): TypedMeshRpc;
+    /**
+     * Build a TypedMeshRpc from an already-constructed raw MeshRpc.
+     * Useful if you need the raw + typed surface side by side.
+     */
+    constructor(rawMeshRpc: RawMeshRpc);
+    /** Underlying raw `MeshRpc` for users who want the Buffer-level surface. */
+    get raw(): RawMeshRpc;
+    /**
+     * Register a typed handler. The handler receives a decoded
+     * `Req` and returns a `Resp` (or a Promise of one). JSON
+     * encode/decode happens at the binding boundary; encode
+     * failure inside the handler surfaces to the caller as
+     * `RpcServerError(status=0x0006 Internal)`.
+     */
+    serve<Req = unknown, Resp = unknown>(service: string, handler: TypedHandler<Req, Resp>): ServeHandle;
+    /**
+     * Direct-addressed typed call. Encodes `req` as JSON, calls,
+     * decodes the response. Throws an `RpcError` subclass on
+     * failure (matched by the napi prefix → JS class mapping in
+     * `errors.js`).
+     *
+     * Pass `opts.signal` (AbortSignal) for caller-driven
+     * cancellation. The wrapper mints a cancel token via the raw
+     * binding's `reserveCancelToken()`, attaches an abort listener,
+     * and lets the abort fire `cancelCall(token)` to drop the in-
+     * flight call (CANCEL fires on the wire, the call rejects with
+     * `nrpc:cancelled:`).
+     */
+    call<Req = unknown, Resp = unknown>(targetNodeId: bigint, service: string, req: Req, opts?: CallOptions): Promise<Resp>;
+    /**
+     * Service-discovery typed call. Resolves `service` against the
+     * local capability index, picks a target per the routing
+     * policy, calls. Throws an `RpcError` subclass on failure.
+     */
+    callService<Req = unknown, Resp = unknown>(service: string, req: Req, opts?: CallOptions): Promise<Resp>;
+    /**
+     * Open a typed streaming call. Returns a `TypedRpcStream` that
+     * yields decoded `Resp` values per `next()` until EOF.
+     */
+    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[];
+    /**
+     * Direct-addressed typed call with retry. See {@link RetryPolicy}.
+     */
+    callWithRetry<Req = unknown, Resp = unknown>(targetNodeId: bigint, service: string, req: Req, opts: CallOptions | undefined, policy: RetryPolicy): Promise<Resp>;
+    /**
+     * Hedge typed call across the listed targets. First reply
+     * (Ok or Err) wins; if every target fails, the surfaced error
+     * is the primary's (target index 0) for stable diagnostics.
+     */
+    callWithHedgeTo<Req = unknown, Resp = unknown>(targets: bigint[], service: string, req: Req, opts: CallOptions | undefined, policy: HedgePolicy): Promise<Resp>;
+}
+export declare class TypedRpcStream<Resp = unknown> implements AsyncIterable<Resp> {
+    private readonly _raw;
+    private _done;
+    constructor(rawRpcStream: RawRpcStream);
+    /**
+     * Pull the next decoded value. Returns `null` on clean EOF.
+     * Throws `RpcCodecError(direction='decode')` if a chunk fails
+     * to decode (terminates the stream — the underlying CANCEL is
+     * fired by the raw RpcStream's drop).
+     */
+    next(): Promise<Resp | null>;
+    /** Async iterator support: `for await (const chunk of stream) { ... }`. */
+    [Symbol.asyncIterator](): AsyncIterator<Resp>;
+    /** Grant `n` flow-control credits to the server pump. */
+    grant(n: number): Promise<void>;
+    /** `true` if the call set `streamWindowInitial`. */
+    flowControlled(): Promise<boolean>;
+    /** Close the stream; emits CANCEL to the server. Idempotent. */
+    close(): Promise<void>;
+}
+export declare function defaultRetryable(err: unknown): boolean;
+export interface RetryPolicyOptions {
+    /** Total attempts (NOT additional retries). Default 3. Must be >= 1. */
+    maxAttempts?: number;
+    /** Backoff before the first retry, in ms. Default 50. */
+    initialBackoffMs?: number;
+    /** Upper bound on per-attempt backoff (true ceiling, after jitter). Default 1000. */
+    maxBackoffMs?: number;
+    /** Multiplicative growth factor between attempts. Default 2.0. */
+    backoffMultiplier?: number;
+    /** Full-half jitter on backoffs. Default true. */
+    jitter?: boolean;
+    /** Predicate: should this error be retried? Default {@link defaultRetryable}. */
+    retryable?: (err: unknown) => boolean;
+}
+/**
+ * Retry policy. Defaults: 3 attempts, 50ms→1s exponential backoff,
+ * full-half jitter on, retryable predicate matches the Rust SDK's
+ * `default_retryable` (skips RpcCodecError, RpcNoRouteError, and
+ * non-transient ServerError statuses).
+ */
+export declare class RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialBackoffMs: number;
+    readonly maxBackoffMs: number;
+    readonly backoffMultiplier: number;
+    readonly jitter: boolean;
+    readonly retryable: (err: unknown) => boolean;
+    constructor(opts?: RetryPolicyOptions);
+    /**
+     * Compute the backoff for `attempt` (1-indexed). Caps at
+     * `maxBackoffMs` AFTER jitter so the cap is a true ceiling.
+     */
+    computeBackoffMs(attempt: number): number;
+}
+export interface HedgePolicyOptions {
+    /** Wait this long after the primary before firing the first hedge. Default 50ms. */
+    delayMs?: number;
+    /** Number of hedge requests in addition to the primary. Default 1. */
+    hedges?: number;
+}
+/**
+ * Hedge policy. Fire-then-race: primary at t=0, hedges at
+ * t = delayMs * idx. First reply wins; if every hedge fails,
+ * the primary's error is surfaced deterministically.
+ */
+export declare class HedgePolicy {
+    readonly delayMs: number;
+    readonly hedges: number;
+    constructor(opts?: HedgePolicyOptions);
+}
+export type BreakerState = 'closed' | 'open' | 'half-open';
+export declare function defaultBreakerFailure(err: unknown): boolean;
+export declare class BreakerOpenError extends Error {
+    constructor();
+}
+export interface CircuitBreakerOptions {
+    /** Consecutive failures before tripping. Default 5. */
+    failureThreshold?: number;
+    /** Cooldown before transitioning Open → HalfOpen. Default 30000. */
+    resetAfterMs?: number;
+    /** Successful probes needed to close from HalfOpen. Default 1. */
+    successThreshold?: number;
+    /** Predicate: does this error count as a failure? Default {@link defaultBreakerFailure}. */
+    failurePredicate?: (err: unknown) => boolean;
+}
+/**
+ * Three-state circuit breaker. Long-lived; instantiate once per
+ * logical downstream and share. `breaker.call(() => ...)`
+ * composes around any async op.
+ */
+export declare class CircuitBreaker {
+    readonly failureThreshold: number;
+    readonly resetAfterMs: number;
+    readonly successThreshold: number;
+    readonly failurePredicate: (err: unknown) => boolean;
+    private _state;
+    private _consecutiveFailures;
+    private _consecutiveSuccesses;
+    private _openedAt;
+    private _probeInFlight;
+    constructor(opts?: CircuitBreakerOptions);
+    state(): BreakerState;
+    consecutiveFailures(): number;
+    reset(): void;
+    /**
+     * Wrap an async op. Returns its value on success, throws on
+     * failure (or on rejection). When the breaker is `Open` within
+     * its cooldown, throws `BreakerOpenError` without invoking
+     * `op`.
+     *
+     * Both success and failure paths record the outcome through
+     * `_recordOutcome`, which is responsible for clearing
+     * `_probeInFlight` on the half-open-probe admission. A
+     * synchronous throw inside `op` (rare — `await` is always at
+     * `op`'s call site) is still routed through the catch arm.
+     */
+    call<T>(op: () => Promise<T>): Promise<T>;
+    private _tryAdmit;
+    private _recordOutcome;
+}
+/**
+ * Build an Error a typed serve handler can throw to surface a
+ * specific application status code to the caller. The Rust
+ * binding parses messages of the form
+ * `nrpc:app_error:0x<code>:<body>` and maps them to
+ * `RpcStatus::Application(code)` — without this prefix the
+ * thrown error becomes a generic `RpcStatus::Internal`. Mirrors
+ * the Python binding's `RpcAppError(code, body)`.
+ *
+ * Use cases: typed handlers that want to return 4xx-style
+ * application errors (`NRPC_TYPED_BAD_REQUEST`,
+ * `NRPC_TYPED_HANDLER_ERROR`, custom app codes >= 0x8000).
+ *
+ * @example
+ *   rpc.serve('echo', (req) => {
+ *     if (typeof req.text !== 'string') {
+ *       throw appError(NRPC_TYPED_BAD_REQUEST,
+ *                      JSON.stringify({error: 'missing text'}))
+ *     }
+ *     return { echo: req.text }
+ *   })
+ */
+export declare function appError(code: number, body: string | Buffer): Error;
+/** RpcStatus::Application(0x8000): typed handler bad-request body. */
+export declare const NRPC_TYPED_BAD_REQUEST: 32768;
+/** RpcStatus::Application(0x8001): typed handler returned `throw`. */
+export declare const NRPC_TYPED_HANDLER_ERROR: 32769;