@actuallab/rpc 12.1.62 → 12.1.100

package/dist/index.d.cts

@@ -13,6 +13,11 @@ declare const RpcSystemCalls: {
     readonly cancel: "$sys.Cancel:0";
     readonly keepAlive: "$sys.KeepAlive:1";
     readonly reconnect: "$sys.Reconnect:3";
+    readonly ack: "$sys.Ack:2";
+    readonly ackEnd: "$sys.AckEnd:1";
+    readonly item: "$sys.I:2";
+    readonly batch: "$sys.B:2";
+    readonly end: "$sys.End:2";
 };
 /** Wire-format RPC message envelope. */
 interface RpcMessage {
@@ -127,20 +132,18 @@ interface RpcMethodDefInput {
     args: unknown[];
     returns?: symbol;
     callTypeId?: number;
-    stream?: boolean;
-    noWait?: boolean;
+    /** Override for wireArgCount. Default: args.length + 1 (assumes a CancellationToken slot). */
+    wireArgCount?: number;
 }
 declare const RpcType: {
     readonly object: symbol;
     readonly stream: symbol;
+    readonly noWait: symbol;
     readonly void: symbol;
 };
-interface RpcServiceDefOptions {
-    ctOffset?: number;
-}
 /** Returns the full wire method name: "ServiceName.MethodName:wireArgCount". */
 declare function wireMethodName(def: RpcMethodDef): string;
-declare function defineRpcService(name: string, methods: Record<string, RpcMethodDefInput>, options?: RpcServiceDefOptions): RpcServiceDef;
+declare function defineRpcService(name: string, methods: Record<string, RpcMethodDefInput>): RpcServiceDef;
 
 /** Tracks a pending outbound RPC call. */
 declare class RpcOutboundCall {
@@ -191,18 +194,6 @@ declare class RpcInboundCallTracker {
     clear(): void;
 }
 
-/** Handles an incoming system call message and dispatches to the appropriate tracker. */
-declare function handleSystemCall(message: RpcMessage, args: unknown[], outboundTracker: RpcOutboundCallTracker, inboundTracker: RpcInboundCallTracker): void;
-
-/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
-declare class RpcSystemCallSender {
-    handshake(conn: RpcConnection, peerId: string, hubId: string, index: number): void;
-    ok(conn: RpcConnection, relatedId: number, result: unknown): void;
-    error(conn: RpcConnection, relatedId: number, error: unknown): void;
-    cancel(conn: RpcConnection, relatedId: number): void;
-    keepAlive(conn: RpcConnection, activeCallIds: number[]): void;
-}
-
 declare class RpcClientPeerReconnectDelayer extends RetryDelayer {
     constructor();
 }
@@ -222,12 +213,29 @@ declare class RpcServiceHost {
     getMethodDef(wireMethod: string): RpcMethodDef | undefined;
 }
 
+/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
+declare class RpcSystemCallSender {
+    handshake(conn: RpcConnection, peerId: string, hubId: string, index: number): void;
+    ok(conn: RpcConnection, relatedId: number, result: unknown): void;
+    error(conn: RpcConnection, relatedId: number, error: unknown): void;
+    cancel(conn: RpcConnection, relatedId: number): void;
+    keepAlive(conn: RpcConnection, activeCallIds: number[]): void;
+    item(conn: RpcConnection, localId: number, index: number, item: unknown): void;
+    batch(conn: RpcConnection, localId: number, index: number, items: unknown[]): void;
+    end(conn: RpcConnection, localId: number, index: number, error?: {
+        Message: string;
+    } | null): void;
+    ack(conn: RpcConnection, localId: number, nextIndex: number, hostId: string): void;
+    ackEnd(conn: RpcConnection, localId: number, hostId: string): void;
+}
+
 /** Central RPC coordinator — manages peers, services, and configuration. */
 declare class RpcHub {
     readonly hubId: string;
     readonly peers: Map<string, RpcPeer>;
     readonly serviceHost: RpcServiceHost;
     readonly systemCallSender: RpcSystemCallSender;
+    systemCallHandler: RpcSystemCallHandler;
     constructor(hubId?: string);
     addPeer(peer: RpcPeer): void;
     removePeer(ref: string): void;
@@ -242,8 +250,6 @@ declare class RpcHub {
     /** Create a typed client proxy for a service on a remote peer. */
     addClient<T extends object>(peer: RpcPeer, defOrContract: RpcServiceDef | (abstract new (...args: any[]) => any)): T;
     close(): void;
-    /** Dispatch an inbound system call. Override in FusionHub to handle compute-specific system calls. */
-    handleSystemCall(message: RpcMessage, args: unknown[], outbound: RpcOutboundCallTracker, inbound: RpcInboundCallTracker): void;
     /** Build an RpcServiceDef from decorator metadata on a contract class. Override in FusionHub for compute support. */
     protected _buildServiceDef(cls: abstract new (...args: any[]) => any): RpcServiceDef;
     /** Resolve a service def from either a plain RpcServiceDef or a contract class. */
@@ -254,6 +260,42 @@ declare class RpcHub {
     protected _createClientMethod(peer: RpcPeer, methodDef: RpcMethodDef): (...args: unknown[]) => unknown;
 }
 
+interface RpcObjectId {
+    readonly hostId: string;
+    readonly localId: number;
+}
+declare const RpcObjectKind: {
+    readonly Local: 0;
+    readonly Remote: 1;
+};
+type RpcObjectKind = (typeof RpcObjectKind)[keyof typeof RpcObjectKind];
+interface IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: RpcObjectKind;
+    readonly allowReconnect: boolean;
+    reconnect(): void;
+    disconnect(): void;
+}
+
+declare class RpcRemoteObjectTracker {
+    private _objects;
+    register(obj: IRpcObject): void;
+    get(localId: number): IRpcObject | undefined;
+    unregister(obj: IRpcObject): void;
+    disconnectAll(): void;
+    reconnectAll(): void;
+}
+
+declare class RpcSharedObjectTracker {
+    private _nextId;
+    private _objects;
+    nextId(): number;
+    register(obj: IRpcObject): void;
+    get(localId: number): IRpcObject | undefined;
+    unregister(obj: IRpcObject): void;
+    disconnectAll(): void;
+}
+
 /**
  * Default serialization format for RpcClientPeer connections.
  * TS uses plain JSON.stringify without polymorphic type wrapping,
@@ -290,6 +332,8 @@ declare abstract class RpcPeer {
     protected _connection: RpcConnection | undefined;
     readonly outbound: RpcOutboundCallTracker;
     readonly inbound: RpcInboundCallTracker;
+    readonly remoteObjects: RpcRemoteObjectTracker;
+    readonly sharedObjects: RpcSharedObjectTracker;
     readonly connected: EventHandlerSet<void>;
     readonly disconnected: EventHandlerSet<{
         code: number;
@@ -298,6 +342,7 @@ declare abstract class RpcPeer {
     protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
     constructor(ref: string, hub: RpcHub);
+    get hub(): RpcHub;
     get connection(): RpcConnection | undefined;
     get isConnected(): boolean;
     protected setupConnection(conn: RpcConnection): void;
@@ -368,6 +413,119 @@ declare class RpcServerPeer extends RpcPeer {
     protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
 }
 
+/** Handles incoming system call messages — class-based equivalent of the former standalone function. */
+declare class RpcSystemCallHandler {
+    handle(message: RpcMessage, args: unknown[], peer: RpcPeer): void;
+}
+
+/** Parsed stream reference from the server's result payload. */
+interface RpcStreamRef {
+    readonly hostId: string;
+    readonly localId: number;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    readonly allowReconnect: boolean;
+}
+/**
+ * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
+ * Returns null if the value is not a valid stream reference.
+ */
+declare function parseStreamRef(value: unknown): RpcStreamRef | null;
+/**
+ * Client-side RPC stream — consumes items sent by the server via system calls
+ * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable<T> for for-await-of consumption.
+ *
+ * Wire protocol:
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ */
+declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: 1;
+    readonly allowReconnect: boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    private _buffer;
+    private _nextExpectedIndex;
+    private _consumerWaiting;
+    private _completed;
+    private _completionError;
+    private _disposed;
+    private _started;
+    private _iterating;
+    private _ackSentUpTo;
+    constructor(ref: RpcStreamRef, peer: RpcPeer);
+    /** Called by system call handler when a single item arrives ($sys.I). */
+    onItem(index: number, item: T): void;
+    /** Called by system call handler when a batch arrives ($sys.B). */
+    onBatch(index: number, items: T[]): void;
+    /** Called by system call handler when the stream ends ($sys.End). */
+    onEnd(index: number, error: Error | null): void;
+    reconnect(): void;
+    disconnect(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    dispose(): void;
+    private _notifyConsumer;
+    private _maybeSendAck;
+    private _sendAck;
+    private _sendAckEnd;
+}
+/**
+ * Recursively walks a deserialized value and replaces any stream ref strings
+ * with live RpcStream<unknown> instances registered on the given peer.
+ * This handles nested stream refs inside complex return types (e.g. Table<T>
+ * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{ackAdvance}").
+ */
+declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
+
+/**
+ * Server-side RPC stream producer — sends items to a remote consumer via
+ * $sys.I / $sys.B / $sys.End system calls.
+ *
+ * Wire protocol (server perspective):
+ * - Server returns the stream reference string as $sys.Ok
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ */
+declare class RpcStreamSender<T> implements IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: 0;
+    readonly allowReconnect: boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    private _nextIndex;
+    private _ended;
+    private _started;
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean);
+    /** Returns the stream reference string for the $sys.Ok response. */
+    toRef(): string;
+    /** Called by system call handler when $sys.Ack is received from the client. */
+    onAck(_nextIndex: number, _hostId: string): void;
+    /** Called by system call handler when $sys.AckEnd is received from the client. */
+    onAckEnd(_hostId: string): void;
+    /** Send a single item to the client. */
+    sendItem(item: T): void;
+    /** Send a batch of items to the client. */
+    sendBatch(items: T[]): void;
+    /** Signal stream completion to the client. */
+    sendEnd(error?: Error | null): void;
+    /**
+     * Consume an AsyncIterable and send all items to the client.
+     * Waits for the client's initial Ack before starting to pump items.
+     */
+    writeFrom(source: AsyncIterable<T>): Promise<void>;
+    reconnect(): void;
+    disconnect(): void;
+}
+
 /** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
 declare function createRpcClient<T extends object>(peer: RpcPeer, serviceDef: RpcServiceDef): T;
 
@@ -379,26 +537,21 @@ interface WebSocketServer {
 
 interface MethodMeta {
     argCount: number;
-    stream?: boolean;
-    noWait?: boolean;
+    returns?: symbol;
     [key: symbol]: unknown;
 }
 interface ServiceMeta {
     name: string;
-    ctOffset?: number;
 }
 /** Read method metadata from a decorated class. */
 declare function getMethodsMeta(cls: abstract new (...args: any[]) => any): Record<string, MethodMeta> | undefined;
 /** Read service metadata from a decorated class. */
 declare function getServiceMeta(cls: abstract new (...args: any[]) => any): ServiceMeta | undefined;
-/** Class decorator — stores the RPC service wire name and optional ctOffset. */
-declare function rpcService(serviceName: string, options?: {
-    ctOffset?: number;
-}): <T extends abstract new (...args: any[]) => any>(_target: T, context: ClassDecoratorContext<T>) => void;
-/** Method decorator — stores RPC method metadata (argCount, stream, noWait). Does NOT wrap the method. */
+/** Class decorator — stores the RPC service wire name. */
+declare function rpcService(serviceName: string): <T extends abstract new (...args: any[]) => any>(_target: T, context: ClassDecoratorContext<T>) => void;
+/** Method decorator — stores RPC method metadata (argCount, returns). Does NOT wrap the method. */
 declare function rpcMethod(options?: {
-    stream?: boolean;
-    noWait?: boolean;
+    returns?: symbol;
 }): <This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
 
 declare const enum RpcPeerStateKind {
@@ -437,4 +590,4 @@ declare class RpcPeerStateMonitor {
     private _scheduleRecompute;
 }
 
-export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type MethodMeta, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, type RpcMessage, RpcMessageChannelConnection, type RpcMethodDef, type RpcMethodDefInput, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcServerPeer, type RpcServiceDef, type RpcServiceDefOptions, RpcServiceHost, type RpcServiceImpl, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, handleSystemCall, isConnected, likelyConnected, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };
+export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, type RpcMessage, RpcMessageChannelConnection, type RpcMethodDef, type RpcMethodDefInput, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcRemoteObjectTracker, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };

package/dist/index.d.ts

@@ -13,6 +13,11 @@ declare const RpcSystemCalls: {
     readonly cancel: "$sys.Cancel:0";
     readonly keepAlive: "$sys.KeepAlive:1";
     readonly reconnect: "$sys.Reconnect:3";
+    readonly ack: "$sys.Ack:2";
+    readonly ackEnd: "$sys.AckEnd:1";
+    readonly item: "$sys.I:2";
+    readonly batch: "$sys.B:2";
+    readonly end: "$sys.End:2";
 };
 /** Wire-format RPC message envelope. */
 interface RpcMessage {
@@ -127,20 +132,18 @@ interface RpcMethodDefInput {
     args: unknown[];
     returns?: symbol;
     callTypeId?: number;
-    stream?: boolean;
-    noWait?: boolean;
+    /** Override for wireArgCount. Default: args.length + 1 (assumes a CancellationToken slot). */
+    wireArgCount?: number;
 }
 declare const RpcType: {
     readonly object: symbol;
     readonly stream: symbol;
+    readonly noWait: symbol;
     readonly void: symbol;
 };
-interface RpcServiceDefOptions {
-    ctOffset?: number;
-}
 /** Returns the full wire method name: "ServiceName.MethodName:wireArgCount". */
 declare function wireMethodName(def: RpcMethodDef): string;
-declare function defineRpcService(name: string, methods: Record<string, RpcMethodDefInput>, options?: RpcServiceDefOptions): RpcServiceDef;
+declare function defineRpcService(name: string, methods: Record<string, RpcMethodDefInput>): RpcServiceDef;
 
 /** Tracks a pending outbound RPC call. */
 declare class RpcOutboundCall {
@@ -191,18 +194,6 @@ declare class RpcInboundCallTracker {
     clear(): void;
 }
 
-/** Handles an incoming system call message and dispatches to the appropriate tracker. */
-declare function handleSystemCall(message: RpcMessage, args: unknown[], outboundTracker: RpcOutboundCallTracker, inboundTracker: RpcInboundCallTracker): void;
-
-/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
-declare class RpcSystemCallSender {
-    handshake(conn: RpcConnection, peerId: string, hubId: string, index: number): void;
-    ok(conn: RpcConnection, relatedId: number, result: unknown): void;
-    error(conn: RpcConnection, relatedId: number, error: unknown): void;
-    cancel(conn: RpcConnection, relatedId: number): void;
-    keepAlive(conn: RpcConnection, activeCallIds: number[]): void;
-}
-
 declare class RpcClientPeerReconnectDelayer extends RetryDelayer {
     constructor();
 }
@@ -222,12 +213,29 @@ declare class RpcServiceHost {
     getMethodDef(wireMethod: string): RpcMethodDef | undefined;
 }
 
+/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
+declare class RpcSystemCallSender {
+    handshake(conn: RpcConnection, peerId: string, hubId: string, index: number): void;
+    ok(conn: RpcConnection, relatedId: number, result: unknown): void;
+    error(conn: RpcConnection, relatedId: number, error: unknown): void;
+    cancel(conn: RpcConnection, relatedId: number): void;
+    keepAlive(conn: RpcConnection, activeCallIds: number[]): void;
+    item(conn: RpcConnection, localId: number, index: number, item: unknown): void;
+    batch(conn: RpcConnection, localId: number, index: number, items: unknown[]): void;
+    end(conn: RpcConnection, localId: number, index: number, error?: {
+        Message: string;
+    } | null): void;
+    ack(conn: RpcConnection, localId: number, nextIndex: number, hostId: string): void;
+    ackEnd(conn: RpcConnection, localId: number, hostId: string): void;
+}
+
 /** Central RPC coordinator — manages peers, services, and configuration. */
 declare class RpcHub {
     readonly hubId: string;
     readonly peers: Map<string, RpcPeer>;
     readonly serviceHost: RpcServiceHost;
     readonly systemCallSender: RpcSystemCallSender;
+    systemCallHandler: RpcSystemCallHandler;
     constructor(hubId?: string);
     addPeer(peer: RpcPeer): void;
     removePeer(ref: string): void;
@@ -242,8 +250,6 @@ declare class RpcHub {
     /** Create a typed client proxy for a service on a remote peer. */
     addClient<T extends object>(peer: RpcPeer, defOrContract: RpcServiceDef | (abstract new (...args: any[]) => any)): T;
     close(): void;
-    /** Dispatch an inbound system call. Override in FusionHub to handle compute-specific system calls. */
-    handleSystemCall(message: RpcMessage, args: unknown[], outbound: RpcOutboundCallTracker, inbound: RpcInboundCallTracker): void;
     /** Build an RpcServiceDef from decorator metadata on a contract class. Override in FusionHub for compute support. */
     protected _buildServiceDef(cls: abstract new (...args: any[]) => any): RpcServiceDef;
     /** Resolve a service def from either a plain RpcServiceDef or a contract class. */
@@ -254,6 +260,42 @@ declare class RpcHub {
     protected _createClientMethod(peer: RpcPeer, methodDef: RpcMethodDef): (...args: unknown[]) => unknown;
 }
 
+interface RpcObjectId {
+    readonly hostId: string;
+    readonly localId: number;
+}
+declare const RpcObjectKind: {
+    readonly Local: 0;
+    readonly Remote: 1;
+};
+type RpcObjectKind = (typeof RpcObjectKind)[keyof typeof RpcObjectKind];
+interface IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: RpcObjectKind;
+    readonly allowReconnect: boolean;
+    reconnect(): void;
+    disconnect(): void;
+}
+
+declare class RpcRemoteObjectTracker {
+    private _objects;
+    register(obj: IRpcObject): void;
+    get(localId: number): IRpcObject | undefined;
+    unregister(obj: IRpcObject): void;
+    disconnectAll(): void;
+    reconnectAll(): void;
+}
+
+declare class RpcSharedObjectTracker {
+    private _nextId;
+    private _objects;
+    nextId(): number;
+    register(obj: IRpcObject): void;
+    get(localId: number): IRpcObject | undefined;
+    unregister(obj: IRpcObject): void;
+    disconnectAll(): void;
+}
+
 /**
  * Default serialization format for RpcClientPeer connections.
  * TS uses plain JSON.stringify without polymorphic type wrapping,
@@ -290,6 +332,8 @@ declare abstract class RpcPeer {
     protected _connection: RpcConnection | undefined;
     readonly outbound: RpcOutboundCallTracker;
     readonly inbound: RpcInboundCallTracker;
+    readonly remoteObjects: RpcRemoteObjectTracker;
+    readonly sharedObjects: RpcSharedObjectTracker;
     readonly connected: EventHandlerSet<void>;
     readonly disconnected: EventHandlerSet<{
         code: number;
@@ -298,6 +342,7 @@ declare abstract class RpcPeer {
     protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
     constructor(ref: string, hub: RpcHub);
+    get hub(): RpcHub;
     get connection(): RpcConnection | undefined;
     get isConnected(): boolean;
     protected setupConnection(conn: RpcConnection): void;
@@ -368,6 +413,119 @@ declare class RpcServerPeer extends RpcPeer {
     protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
 }
 
+/** Handles incoming system call messages — class-based equivalent of the former standalone function. */
+declare class RpcSystemCallHandler {
+    handle(message: RpcMessage, args: unknown[], peer: RpcPeer): void;
+}
+
+/** Parsed stream reference from the server's result payload. */
+interface RpcStreamRef {
+    readonly hostId: string;
+    readonly localId: number;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    readonly allowReconnect: boolean;
+}
+/**
+ * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
+ * Returns null if the value is not a valid stream reference.
+ */
+declare function parseStreamRef(value: unknown): RpcStreamRef | null;
+/**
+ * Client-side RPC stream — consumes items sent by the server via system calls
+ * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable<T> for for-await-of consumption.
+ *
+ * Wire protocol:
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ */
+declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: 1;
+    readonly allowReconnect: boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    private _buffer;
+    private _nextExpectedIndex;
+    private _consumerWaiting;
+    private _completed;
+    private _completionError;
+    private _disposed;
+    private _started;
+    private _iterating;
+    private _ackSentUpTo;
+    constructor(ref: RpcStreamRef, peer: RpcPeer);
+    /** Called by system call handler when a single item arrives ($sys.I). */
+    onItem(index: number, item: T): void;
+    /** Called by system call handler when a batch arrives ($sys.B). */
+    onBatch(index: number, items: T[]): void;
+    /** Called by system call handler when the stream ends ($sys.End). */
+    onEnd(index: number, error: Error | null): void;
+    reconnect(): void;
+    disconnect(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    dispose(): void;
+    private _notifyConsumer;
+    private _maybeSendAck;
+    private _sendAck;
+    private _sendAckEnd;
+}
+/**
+ * Recursively walks a deserialized value and replaces any stream ref strings
+ * with live RpcStream<unknown> instances registered on the given peer.
+ * This handles nested stream refs inside complex return types (e.g. Table<T>
+ * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{ackAdvance}").
+ */
+declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
+
+/**
+ * Server-side RPC stream producer — sends items to a remote consumer via
+ * $sys.I / $sys.B / $sys.End system calls.
+ *
+ * Wire protocol (server perspective):
+ * - Server returns the stream reference string as $sys.Ok
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ */
+declare class RpcStreamSender<T> implements IRpcObject {
+    readonly id: RpcObjectId;
+    readonly kind: 0;
+    readonly allowReconnect: boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly ackAdvance: number;
+    private _nextIndex;
+    private _ended;
+    private _started;
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean);
+    /** Returns the stream reference string for the $sys.Ok response. */
+    toRef(): string;
+    /** Called by system call handler when $sys.Ack is received from the client. */
+    onAck(_nextIndex: number, _hostId: string): void;
+    /** Called by system call handler when $sys.AckEnd is received from the client. */
+    onAckEnd(_hostId: string): void;
+    /** Send a single item to the client. */
+    sendItem(item: T): void;
+    /** Send a batch of items to the client. */
+    sendBatch(items: T[]): void;
+    /** Signal stream completion to the client. */
+    sendEnd(error?: Error | null): void;
+    /**
+     * Consume an AsyncIterable and send all items to the client.
+     * Waits for the client's initial Ack before starting to pump items.
+     */
+    writeFrom(source: AsyncIterable<T>): Promise<void>;
+    reconnect(): void;
+    disconnect(): void;
+}
+
 /** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
 declare function createRpcClient<T extends object>(peer: RpcPeer, serviceDef: RpcServiceDef): T;
 
@@ -379,26 +537,21 @@ interface WebSocketServer {
 
 interface MethodMeta {
     argCount: number;
-    stream?: boolean;
-    noWait?: boolean;
+    returns?: symbol;
     [key: symbol]: unknown;
 }
 interface ServiceMeta {
     name: string;
-    ctOffset?: number;
 }
 /** Read method metadata from a decorated class. */
 declare function getMethodsMeta(cls: abstract new (...args: any[]) => any): Record<string, MethodMeta> | undefined;
 /** Read service metadata from a decorated class. */
 declare function getServiceMeta(cls: abstract new (...args: any[]) => any): ServiceMeta | undefined;
-/** Class decorator — stores the RPC service wire name and optional ctOffset. */
-declare function rpcService(serviceName: string, options?: {
-    ctOffset?: number;
-}): <T extends abstract new (...args: any[]) => any>(_target: T, context: ClassDecoratorContext<T>) => void;
-/** Method decorator — stores RPC method metadata (argCount, stream, noWait). Does NOT wrap the method. */
+/** Class decorator — stores the RPC service wire name. */
+declare function rpcService(serviceName: string): <T extends abstract new (...args: any[]) => any>(_target: T, context: ClassDecoratorContext<T>) => void;
+/** Method decorator — stores RPC method metadata (argCount, returns). Does NOT wrap the method. */
 declare function rpcMethod(options?: {
-    stream?: boolean;
-    noWait?: boolean;
+    returns?: symbol;
 }): <This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
 
 declare const enum RpcPeerStateKind {
@@ -437,4 +590,4 @@ declare class RpcPeerStateMonitor {
     private _scheduleRecompute;
 }
 
-export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type MethodMeta, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, type RpcMessage, RpcMessageChannelConnection, type RpcMethodDef, type RpcMethodDefInput, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcServerPeer, type RpcServiceDef, type RpcServiceDefOptions, RpcServiceHost, type RpcServiceImpl, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, handleSystemCall, isConnected, likelyConnected, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };
+export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, type RpcMessage, RpcMessageChannelConnection, type RpcMethodDef, type RpcMethodDefInput, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcRemoteObjectTracker, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };