actor-ts 0.9.0

package/dist/cluster/Protocol.d.ts

@@ -0,0 +1,151 @@
+import { NodeAddress, type NodeAddressData } from './NodeAddress.js';
+/**
+ * Lifecycle state of a cluster member.
+ *   - `joining`    — announced itself, not yet part of the active set.
+ *   - `weakly-up`  — reachable and has been waiting for leader convergence
+ *     for a while; allowed to route traffic but isn't yet part of the
+ *     leader-elected active set.  Transitioned to `up` on convergence.
+ *   - `up`         — active member, receives and routes work.
+ *   - `unreachable`— heartbeats missing; may recover.
+ *   - `leaving`    — graceful shutdown in progress.
+ *   - `down`       — declared dead, pending removal.
+ *   - `removed`    — terminal state.  On the **definitive-removal**
+ *     paths (`handleLeave`, downing-provider force-down) the entry
+ *     is kept in the local members map as a **tombstone** with a
+ *     `removedAt` timestamp so stale gossip can't resurrect the
+ *     address; the tombstone is reclaimed once `tombstoneTtlMs`
+ *     (default 24 h) elapses.  On the **FD-driven** path the entry
+ *     is deleted outright so a healed partition can re-discover
+ *     the peer.  Public APIs (`getMembers`, `upMembers`,
+ *     `reachableMembers`) and `Member.isReachable()` all filter
+ *     `removed` out — only direct iteration of the raw map needs
+ *     to check the status explicitly.  See #75 + the
+ *     {@link MemberRemoved} JSDoc.
+ */
+export type MemberStatus = 'joining' | 'weakly-up' | 'up' | 'unreachable' | 'leaving' | 'down' | 'removed';
+export interface MemberData {
+    readonly address: NodeAddressData;
+    readonly status: MemberStatus;
+    /** Monotonic version clock; higher value wins during gossip merges. */
+    readonly version: number;
+    /** Arbitrary role tags used to filter placement (e.g. "backend"). */
+    readonly roles?: string[];
+    /**
+     * Wall-clock instant at which the tombstone was created, set only
+     * when `status === 'removed'` (#75).  Travels in gossip so every
+     * peer prunes the tombstone at roughly the same wall-clock time;
+     * absent on non-tombstone members and on tombstones created by
+     * older nodes that pre-date this field — see `mergeMember` for
+     * the back-compat handling.
+     */
+    readonly removedAt?: number;
+}
+/**
+ * Every wire message carries a discriminator `t`.  Payload types that contain
+ * user messages use `body` which is assumed to be JSON-safe.
+ */
+export type WireMessage = HelloMsg | HelloAckMsg | HeartbeatMsg | HeartbeatAckMsg | GossipMsg | EnvelopeMsg | ShardMapMsg | LeaveMsg;
+export interface HelloMsg {
+    t: 'hello';
+    self: NodeAddressData;
+}
+export interface HelloAckMsg {
+    t: 'hello-ack';
+    self: NodeAddressData;
+}
+export interface HeartbeatMsg {
+    t: 'heartbeat';
+    from: NodeAddressData;
+    seq: number;
+    ts: number;
+}
+export interface HeartbeatAckMsg {
+    t: 'heartbeat-ack';
+    from: NodeAddressData;
+    seq: number;
+}
+export interface GossipMsg {
+    t: 'gossip';
+    from: NodeAddressData;
+    members: MemberData[];
+}
+export interface EnvelopeMsg {
+    t: 'envelope';
+    /** Full actor path string of the recipient on the target node. */
+    to: string;
+    /** Full actor path string of the sender, or null. */
+    from: string | null;
+    /** JSON-safe payload. */
+    body: unknown;
+    /** Optional: name of a class/type for richer routing. */
+    tag?: string;
+    /**
+     * Optional MDC snapshot captured at tell-time on the originating
+     * node.  Re-installed by `Cluster.handleEnvelope` so the receiving
+     * actor's log lines carry the same context as the sender's
+     * (#53 — cross-node MDC).
+     */
+    context?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Optional W3C trace context — the `traceparent` value carrying
+     * the originating node's active span.  The receiving cluster
+     * decodes it and links the new actor.receive span to that parent
+     * (#10 — cross-node distributed tracing).
+     */
+    trace?: {
+        readonly traceparent: string;
+        readonly tracestate?: string;
+    };
+}
+export interface ShardMapMsg {
+    t: 'shard-map';
+    type: string;
+    shards: Record<number, NodeAddressData>;
+    version: number;
+}
+export interface LeaveMsg {
+    t: 'leave';
+    node: NodeAddressData;
+}
+/** Encode a WireMessage as a length-prefixed JSON frame. */
+export declare function encodeFrame(msg: WireMessage): Uint8Array;
+/**
+ * Default cap on a single frame's payload size — 16 MiB.  Anything
+ * larger is rejected by {@link FrameDecoder} before the buffer grows.
+ *
+ * **Why this exists (security):** the wire format prefixes each
+ * payload with a 4-byte big-endian uint32, so a malicious or
+ * malformed peer can claim a 4 GiB length and force the decoder to
+ * either buffer up to that size (OOM) or wait indefinitely for the
+ * rest of the bytes (DoS).  Capping at a sensible default closes
+ * that vector; callers that genuinely send larger frames can raise
+ * the cap via the `FrameDecoder` constructor or
+ * `TcpTransport`'s settings.
+ */
+export declare const DEFAULT_MAX_FRAME_BYTES: number;
+/**
+ * Incremental decoder that buffers bytes across multiple chunks and yields
+ * whole frames.  TCP gives no message boundaries — the caller feeds bytes as
+ * they arrive and collects whatever frames completed.
+ *
+ * **Frame-size cap (security):** the optional `maxFrameBytes`
+ * constructor arg (default {@link DEFAULT_MAX_FRAME_BYTES}) rejects
+ * frames whose claimed length-prefix exceeds the cap — before any
+ * payload bytes are buffered.  An attacker claiming a 4 GiB frame
+ * hits the cap immediately and the decoder throws, so neither OOM
+ * nor an indefinite stall is possible.
+ */
+export declare class FrameDecoder {
+    private buffer;
+    private readonly maxFrameBytes;
+    constructor(maxFrameBytes?: number);
+    push(chunk: Uint8Array): WireMessage[];
+}
+export declare const Protocol: {
+    encodeFrame: typeof encodeFrame;
+    NodeAddress: {
+        toData: (a: NodeAddress) => NodeAddressData;
+        fromData: (d: NodeAddressData) => NodeAddress;
+    };
+};
+//# sourceMappingURL=Protocol.d.ts.map

package/dist/cluster/Protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Protocol.d.ts","sourceRoot":"","sources":["../../src/cluster/Protocol.ts"],"names":[],"mappings":"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"}

package/dist/cluster/Protocol.js

@@ -0,0 +1,90 @@
+import { NodeAddress } from './NodeAddress.js';
+/* -------------------------------- Framing -------------------------------- */
+const HEADER_SIZE = 4;
+/** Encode a WireMessage as a length-prefixed JSON frame. */
+export function encodeFrame(msg) {
+    const json = JSON.stringify(msg);
+    const payload = new TextEncoder().encode(json);
+    const frame = new Uint8Array(HEADER_SIZE + payload.byteLength);
+    const view = new DataView(frame.buffer);
+    view.setUint32(0, payload.byteLength, false); // big-endian
+    frame.set(payload, HEADER_SIZE);
+    return frame;
+}
+/**
+ * Default cap on a single frame's payload size — 16 MiB.  Anything
+ * larger is rejected by {@link FrameDecoder} before the buffer grows.
+ *
+ * **Why this exists (security):** the wire format prefixes each
+ * payload with a 4-byte big-endian uint32, so a malicious or
+ * malformed peer can claim a 4 GiB length and force the decoder to
+ * either buffer up to that size (OOM) or wait indefinitely for the
+ * rest of the bytes (DoS).  Capping at a sensible default closes
+ * that vector; callers that genuinely send larger frames can raise
+ * the cap via the `FrameDecoder` constructor or
+ * `TcpTransport`'s settings.
+ */
+export const DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024;
+/**
+ * Incremental decoder that buffers bytes across multiple chunks and yields
+ * whole frames.  TCP gives no message boundaries — the caller feeds bytes as
+ * they arrive and collects whatever frames completed.
+ *
+ * **Frame-size cap (security):** the optional `maxFrameBytes`
+ * constructor arg (default {@link DEFAULT_MAX_FRAME_BYTES}) rejects
+ * frames whose claimed length-prefix exceeds the cap — before any
+ * payload bytes are buffered.  An attacker claiming a 4 GiB frame
+ * hits the cap immediately and the decoder throws, so neither OOM
+ * nor an indefinite stall is possible.
+ */
+export class FrameDecoder {
+    buffer = new Uint8Array(0);
+    maxFrameBytes;
+    constructor(maxFrameBytes = DEFAULT_MAX_FRAME_BYTES) {
+        if (!Number.isFinite(maxFrameBytes) || maxFrameBytes < 1) {
+            throw new Error(`FrameDecoder: maxFrameBytes must be a positive integer, got ${maxFrameBytes}`);
+        }
+        this.maxFrameBytes = Math.trunc(maxFrameBytes);
+    }
+    push(chunk) {
+        this.buffer = concat(this.buffer, chunk);
+        const out = [];
+        const decoder = new TextDecoder();
+        while (this.buffer.byteLength >= HEADER_SIZE) {
+            const len = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength).getUint32(0, false);
+            if (len > this.maxFrameBytes) {
+                // Reject BEFORE buffering — the attacker can't force an OOM
+                // by claiming a 4 GiB frame.  Throwing here triggers
+                // connection-shutdown in the transport layer.
+                throw new Error(`wire frame claims length ${len} > maxFrameBytes ${this.maxFrameBytes} — `
+                    + `connection terminated to prevent OOM/DoS`);
+            }
+            if (this.buffer.byteLength < HEADER_SIZE + len)
+                break;
+            const payload = this.buffer.subarray(HEADER_SIZE, HEADER_SIZE + len);
+            const json = decoder.decode(payload);
+            this.buffer = this.buffer.subarray(HEADER_SIZE + len);
+            try {
+                out.push(JSON.parse(json));
+            }
+            catch (e) {
+                throw new Error(`Invalid wire frame JSON: ${e.message}`);
+            }
+        }
+        return out;
+    }
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a, 0);
+    out.set(b, a.byteLength);
+    return out;
+}
+export const Protocol = {
+    encodeFrame,
+    NodeAddress: {
+        toData: (a) => a.toJSON(),
+        fromData: (d) => NodeAddress.fromJSON(d),
+    },
+};
+//# sourceMappingURL=Protocol.js.map

package/dist/cluster/Protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Protocol.js","sourceRoot":"","sources":["../../src/cluster/Protocol.ts"],"names":[],"mappings":"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"}

package/dist/cluster/RefCodec.d.ts

@@ -0,0 +1,40 @@
+import { NodeAddress } from './NodeAddress.js';
+import type { Cluster } from './Cluster.js';
+/**
+ * Wire representation of an `ActorRef` — a plain JSON-safe object that
+ * round-trips through `JSON.stringify` / `JSON.parse` and can be rebuilt
+ * into a real ref on the receiving node.
+ *
+ * Refs for `Nobody` (the no-op ref) are encoded with `path: 'nobody'` and
+ * no address fields.  All other refs carry the full owning-node address so
+ * the receiver knows where to dial back.
+ */
+export interface WireActorRef {
+    readonly $ref: 'actor';
+    readonly path: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly system?: string;
+}
+export declare function isWireActorRef(v: unknown): v is WireActorRef;
+/**
+ * Recursively walk a user message value and replace every `ActorRef`
+ * instance with a `WireActorRef` marker.  Local refs (including the
+ * short-lived ask-response ref and `DeadLetterRef`) are stamped with
+ * `fromAddress` so the receiver can reconstruct a `RemoteActorRef`
+ * pointing back here.  Remote refs carry their existing target node.
+ * `Nobody` becomes a sentinel marker.
+ *
+ * Non-ref values pass through untouched — this walker only rewrites refs.
+ */
+export declare function encodeRefs(value: unknown, fromAddress: NodeAddress): unknown;
+/**
+ * Recursively walk a parsed wire value and replace every `WireActorRef`
+ * marker with a live `ActorRef` — a local resolution if the marker points
+ * at this cluster's own `selfAddress`, a `RemoteActorRef` otherwise.
+ * Missing or malformed markers fall back to `Nobody`.
+ */
+export declare function decodeRefs(value: unknown, cluster: Cluster): unknown;
+/** Extract the "user/foo/bar" segments from "actor-ts://system/user/foo/bar". */
+export declare function parsePathSegments(path: string): string[];
+//# sourceMappingURL=RefCodec.d.ts.map

package/dist/cluster/RefCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefCodec.d.ts","sourceRoot":"","sources":["../../src/cluster/RefCodec.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,YAAY,CAI5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpE;AA4CD,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKxD"}

package/dist/cluster/RefCodec.js

@@ -0,0 +1,134 @@
+import { ActorRef, Nobody, NobodyRef } from '../ActorRef.js';
+import { NodeAddress } from './NodeAddress.js';
+import { RemoteActorRef } from './RemoteActorRef.js';
+const WIRE_REF_TAG = 'actor';
+export function isWireActorRef(v) {
+    return typeof v === 'object' && v !== null
+        && v.$ref === WIRE_REF_TAG
+        && typeof v.path === 'string';
+}
+/**
+ * Recursively walk a user message value and replace every `ActorRef`
+ * instance with a `WireActorRef` marker.  Local refs (including the
+ * short-lived ask-response ref and `DeadLetterRef`) are stamped with
+ * `fromAddress` so the receiver can reconstruct a `RemoteActorRef`
+ * pointing back here.  Remote refs carry their existing target node.
+ * `Nobody` becomes a sentinel marker.
+ *
+ * Non-ref values pass through untouched — this walker only rewrites refs.
+ */
+export function encodeRefs(value, fromAddress) {
+    return walk(value, (ref) => encodeSingleRef(ref, fromAddress), new WeakSet());
+}
+/**
+ * Recursively walk a parsed wire value and replace every `WireActorRef`
+ * marker with a live `ActorRef` — a local resolution if the marker points
+ * at this cluster's own `selfAddress`, a `RemoteActorRef` otherwise.
+ * Missing or malformed markers fall back to `Nobody`.
+ */
+export function decodeRefs(value, cluster) {
+    return walkDecode(value, cluster, new WeakSet());
+}
+/* ------------------------------ internals -------------------------------- */
+function encodeSingleRef(ref, fromAddress) {
+    if (ref instanceof NobodyRef) {
+        return { $ref: WIRE_REF_TAG, path: 'nobody' };
+    }
+    if (ref instanceof RemoteActorRef) {
+        return {
+            $ref: WIRE_REF_TAG,
+            path: ref.targetPath,
+            host: ref.targetNode.host,
+            port: ref.targetNode.port,
+            system: ref.targetNode.systemName,
+        };
+    }
+    // Local refs (LocalActorRef / ask-response ref / DeadLetterRef) — tag
+    // with our own address so the other side can send back to us.
+    return {
+        $ref: WIRE_REF_TAG,
+        path: ref.path.toString(),
+        host: fromAddress.host,
+        port: fromAddress.port,
+        system: fromAddress.systemName,
+    };
+}
+function decodeSingleRef(wire, cluster) {
+    if (wire.path === 'nobody' || !wire.host || !wire.port || !wire.system) {
+        return Nobody;
+    }
+    const self = cluster.selfAddress;
+    // Same node: hand back the local ref.  Actors that no longer exist fall
+    // through to Nobody rather than constructing a dangling RemoteActorRef
+    // back to ourselves.
+    if (wire.host === self.host && wire.port === self.port && wire.system === self.systemName) {
+        const segs = parsePathSegments(wire.path);
+        return cluster.system._resolvePath(segs).getOrElse(Nobody);
+    }
+    const targetNode = new NodeAddress(wire.system, wire.host, wire.port);
+    return new RemoteActorRef(targetNode, wire.path, cluster);
+}
+/** Extract the "user/foo/bar" segments from "actor-ts://system/user/foo/bar". */
+export function parsePathSegments(path) {
+    const match = /^actor-ts:\/\/[^/]+\/?(.*)$/.exec(path);
+    if (!match)
+        return [];
+    const rest = match[1] ?? '';
+    return rest.split('/').filter((s) => s.length > 0);
+}
+function walk(value, encodeRef, seen) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    if (value instanceof ActorRef)
+        return encodeRef(value);
+    // Types JSON already handles (or silently lossy): leave alone.
+    if (value instanceof Date)
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (seen.has(value))
+        return null; // break cycles
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((v) => walk(v, encodeRef, seen));
+    }
+    if (value instanceof Map) {
+        // Best-effort: walk values (JSON.stringify flattens Maps to {} anyway).
+        const out = new Map();
+        for (const [k, v] of value.entries())
+            out.set(k, walk(v, encodeRef, seen));
+        return out;
+    }
+    if (value instanceof Set) {
+        return new Set(Array.from(value).map((v) => walk(v, encodeRef, seen)));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = walk(v, encodeRef, seen);
+    }
+    return out;
+}
+function walkDecode(value, cluster, seen) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    if (isWireActorRef(value))
+        return decodeSingleRef(value, cluster);
+    if (value instanceof Date || value instanceof Uint8Array)
+        return value;
+    if (seen.has(value))
+        return null;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((v) => walkDecode(v, cluster, seen));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = walkDecode(v, cluster, seen);
+    }
+    return out;
+}
+//# sourceMappingURL=RefCodec.js.map

package/dist/cluster/RefCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefCodec.js","sourceRoot":"","sources":["../../src/cluster/RefCodec.ts"],"names":[],"mappings":"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"}

package/dist/cluster/RemoteActorRef.d.ts

@@ -0,0 +1,22 @@
+import { ActorPath } from '../ActorPath.js';
+import { ActorRef } from '../ActorRef.js';
+import type { Cluster } from './Cluster.js';
+import type { NodeAddress } from './NodeAddress.js';
+/**
+ * A ref whose target lives on a different node.  tell() builds an envelope
+ * and hands it to the cluster transport.  Messages MUST be JSON-safe;
+ * classes are not preserved by default (only the tag string is sent).
+ * Any `ActorRef` instances embedded in the message body are rewritten to
+ * wire-safe markers inside `Cluster._sendEnvelope` so they can be
+ * reconstructed on the receiving node.
+ */
+export declare class RemoteActorRef<TMsg = unknown> extends ActorRef<TMsg> {
+    readonly targetNode: NodeAddress;
+    readonly targetPath: string;
+    private readonly cluster;
+    readonly path: ActorPath;
+    constructor(targetNode: NodeAddress, targetPath: string, cluster: Cluster);
+    tell(message: TMsg, sender?: ActorRef | null): void;
+    toString(): string;
+}
+//# sourceMappingURL=RemoteActorRef.d.ts.map

package/dist/cluster/RemoteActorRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteActorRef.d.ts","sourceRoot":"","sources":["../../src/cluster/RemoteActorRef.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;;;;;GAOG;AACH,qBAAa,cAAc,CAAC,IAAI,GAAG,OAAO,CAAE,SAAQ,QAAQ,CAAC,IAAI,CAAC;aAI9C,UAAU,EAAE,WAAW;aACvB,UAAU,EAAE,MAAM;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAGP,UAAU,EAAE,WAAW,EACvB,UAAU,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO;IAWnC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,GAAE,QAAQ,GAAG,IAAW,GAAG,IAAI;IAmBhD,QAAQ,IAAI,MAAM;CAG5B"}

package/dist/cluster/RemoteActorRef.js

@@ -0,0 +1,48 @@
+import { ActorPath } from '../ActorPath.js';
+import { ActorRef } from '../ActorRef.js';
+import { LogContext } from '../LogContext.js';
+import { tracerOf } from '../tracing/TracingExtension.js';
+/**
+ * A ref whose target lives on a different node.  tell() builds an envelope
+ * and hands it to the cluster transport.  Messages MUST be JSON-safe;
+ * classes are not preserved by default (only the tag string is sent).
+ * Any `ActorRef` instances embedded in the message body are rewritten to
+ * wire-safe markers inside `Cluster._sendEnvelope` so they can be
+ * reconstructed on the receiving node.
+ */
+export class RemoteActorRef extends ActorRef {
+    targetNode;
+    targetPath;
+    cluster;
+    path;
+    constructor(targetNode, targetPath, cluster) {
+        super();
+        this.targetNode = targetNode;
+        this.targetPath = targetPath;
+        this.cluster = cluster;
+        // Remote path doesn't have a local parent hierarchy; rebuild minimally.
+        this.path = new ActorPath(targetPath.split('/').pop() ?? 'remote', null, targetNode.systemName);
+    }
+    tell(message, sender = null) {
+        // Snapshot caller's MDC + W3C trace context at tell-time so the
+        // receiving node can re-install both before delivering to the
+        // local actor (#53, #10).  Empty values are omitted so the wire
+        // envelope stays unchanged on the no-instrumentation hot path.
+        const ctx = LogContext.get();
+        const trace = tracerOf(this.cluster.system).injectContext();
+        const envelope = {
+            t: 'envelope',
+            to: this.targetPath,
+            from: sender ? sender.path.toString() : null,
+            body: message,
+            tag: message?.constructor?.name,
+            ...(Object.keys(ctx).length > 0 ? { context: ctx } : {}),
+            ...(trace ? { trace } : {}),
+        };
+        this.cluster._sendEnvelope(this.targetNode, envelope);
+    }
+    toString() {
+        return `${this.targetNode}${this.targetPath}`;
+    }
+}
+//# sourceMappingURL=RemoteActorRef.js.map

package/dist/cluster/RemoteActorRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteActorRef.js","sourceRoot":"","sources":["../../src/cluster/RemoteActorRef.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAK1D;;;;;;;GAOG;AACH,MAAM,OAAO,cAA+B,SAAQ,QAAc;IAI9C;IACA;IACC;IALV,IAAI,CAAY;IAEzB,YACkB,UAAuB,EACvB,UAAkB,EACjB,OAAgB;QAEjC,KAAK,EAAE,CAAC;QAJQ,eAAU,GAAV,UAAU,CAAa;QACvB,eAAU,GAAV,UAAU,CAAQ;QACjB,YAAO,GAAP,OAAO,CAAS;QAGjC,wEAAwE;QACxE,IAAI,CAAC,IAAI,GAAG,IAAI,SAAS,CACvB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,QAAQ,EACvC,IAAI,EACJ,UAAU,CAAC,UAAU,CACtB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,OAAa,EAAE,SAA0B,IAAI;QAChD,gEAAgE;QAChE,8DAA8D;QAC9D,gEAAgE;QAChE,+DAA+D;QAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC;QAC5D,MAAM,QAAQ,GAAgB;YAC5B,CAAC,EAAE,UAAU;YACb,EAAE,EAAE,IAAI,CAAC,UAAU;YACnB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI;YAC5C,IAAI,EAAE,OAAkB;YACxB,GAAG,EAAG,OAA+C,EAAE,WAAW,EAAE,IAAI;YACxE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5B,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAEQ,QAAQ;QACf,OAAO,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IAChD,CAAC;CACF"}

package/dist/cluster/Transport.d.ts

@@ -0,0 +1,96 @@
+import type { Logger } from '../Logger.js';
+import { type TlsTransportSettings } from '../runtime/tcp/index.js';
+import { NodeAddress } from './NodeAddress.js';
+import { type WireMessage } from './Protocol.js';
+export type WireHandler = (from: NodeAddress, msg: WireMessage) => void;
+export type { TlsTransportSettings };
+/**
+ * Lower-level networking interface consumed by the Cluster.  The TCP
+ * implementation is the production one; tests use an in-memory transport
+ * that loops frames through JS structures.
+ */
+export interface Transport {
+    readonly self: NodeAddress;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    setHandler(handler: WireHandler): void;
+    /** Best-effort fire-and-forget send. Opens a connection on first use. */
+    send(to: NodeAddress, msg: WireMessage): void;
+    /** Close the connection to a peer. */
+    disconnect(peer: NodeAddress): void;
+    /** Peers currently connected (either inbound or outbound). */
+    peers(): NodeAddress[];
+}
+/**
+ * TCP-backed cluster transport.  Wire framing lives in `Protocol.ts`; the
+ * actual socket API is plugged in per runtime via `TcpBackend`
+ * (`src/runtime/tcp/`), so this class is identical on Bun, Node.js, and
+ * Deno — the differences in listen/connect/socket shape are absorbed by
+ * the adapter.
+ *
+ * Per-connection state is tracked in a `WeakMap<TcpSocketLike, Conn>` —
+ * `TcpSocketLike` is intentionally opaque and has no stash slot.
+ */
+export declare class TcpTransport implements Transport {
+    readonly self: NodeAddress;
+    private readonly log;
+    /** Optional TLS configuration — when set, both listener and dialer use TLS. */
+    private readonly tls;
+    /**
+     * Per-frame size cap (security).  Frames whose length-prefix
+     * exceeds this are rejected before any payload bytes are
+     * buffered — closes the 4-GiB-claim DoS vector documented on
+     * {@link FrameDecoder}.  Default: {@link DEFAULT_MAX_FRAME_BYTES}
+     * (16 MiB).  Raise it only if you genuinely send larger
+     * envelopes; the cap is per-frame, not aggregate.
+     */
+    private readonly maxFrameBytes;
+    private backend;
+    private listener;
+    private byPeer;
+    private bySocket;
+    private handler;
+    private stopped;
+    constructor(self: NodeAddress, log: Logger, 
+    /** Optional TLS configuration — when set, both listener and dialer use TLS. */
+    tls?: TlsTransportSettings | null, 
+    /**
+     * Per-frame size cap (security).  Frames whose length-prefix
+     * exceeds this are rejected before any payload bytes are
+     * buffered — closes the 4-GiB-claim DoS vector documented on
+     * {@link FrameDecoder}.  Default: {@link DEFAULT_MAX_FRAME_BYTES}
+     * (16 MiB).  Raise it only if you genuinely send larger
+     * envelopes; the cap is per-frame, not aggregate.
+     */
+    maxFrameBytes?: number);
+    setHandler(handler: WireHandler): void;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    send(to: NodeAddress, msg: WireMessage): void;
+    disconnect(peer: NodeAddress): void;
+    peers(): NodeAddress[];
+    private attachInbound;
+    private openOutbound;
+    private onData;
+    private onMessage;
+    private onClose;
+}
+/**
+ * A transport that keeps everything inside the current process.  Useful for
+ * tests where we want to simulate a cluster without opening TCP sockets.
+ */
+export declare class InMemoryTransport implements Transport {
+    readonly self: NodeAddress;
+    /** Shared registry so peer transports find each other. */
+    private static registry;
+    private handler;
+    private stopped;
+    constructor(self: NodeAddress);
+    setHandler(handler: WireHandler): void;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    send(to: NodeAddress, msg: WireMessage): void;
+    disconnect(_peer: NodeAddress): void;
+    peers(): NodeAddress[];
+}
+//# sourceMappingURL=Transport.d.ts.map

package/dist/cluster/Transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.d.ts","sourceRoot":"","sources":["../../src/cluster/Transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,yEAAyE;IACzE,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9C,sCAAsC;IACtC,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,8DAA8D;IAC9D,KAAK,IAAI,WAAW,EAAE,CAAC;CACxB;AAaD;;;;;;;;;GASG;AACH,qBAAa,YAAa,YAAW,SAAS;IAS1C,QAAQ,CAAC,IAAI,EAAE,WAAW;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa;IApBhC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,OAAO,CAAS;gBAGb,IAAI,EAAE,WAAW,EACT,GAAG,EAAE,MAAM;IAC5B,+EAA+E;IAC9D,GAAG,GAAE,oBAAoB,GAAG,IAAW;IACxD;;;;;;;OAOG;IACc,aAAa,GAAE,MAAgC;IAGlE,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAEhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAY/B,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAU7C,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAOnC,KAAK,IAAI,WAAW,EAAE;IAQtB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,MAAM;IA2Bd,OAAO,CAAC,SAAS;IA0DjB,OAAO,CAAC,OAAO;CAMhB;AAID;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IAOrC,QAAQ,CAAC,IAAI,EAAE,WAAW;IANtC,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAwC;IAE/D,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,OAAO,CAAS;gBAEH,IAAI,EAAE,WAAW;IAEtC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAEhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI;IAW7C,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAEpC,KAAK,IAAI,WAAW,EAAE;CAKvB"}