@zlink-systems/framework 0.10.0

package/dist/runtime/streams/managed-stream.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkManagedStream = void 0;
+exports.streamSessionIdFromRoutingId = streamSessionIdFromRoutingId;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const submission_result_1 = require("../messaging/submission-result");
+const abort_1 = require("../abort");
+const payload_codec_1 = require("../messaging/payload-codec");
+const runtime_values_1 = require("../backend/runtime-values");
+const runtime_message_1 = require("../backend/runtime-message");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const protocol_1 = require("./protocol");
+const ZLINK_SEND_DONT_WAIT = 1;
+const NO_ACCEPTED_TERMINAL_RESULTS = new Set();
+const IDEMPOTENT_UNBIND_TERMINAL_RESULTS = new Set([
+    runtime_values_1.RequestResult.NotConnected,
+    runtime_values_1.RequestResult.NotFound
+]);
+class ZLinkManagedStream {
+    socket;
+    backendSessionRoutingId;
+    messageSerializers;
+    nativeSessionService;
+    meshCompletions;
+    publicSessionId;
+    nativeSessionRouteForMesh;
+    currentLocalAddr;
+    currentRemoteAddr;
+    transportClosed = false;
+    nativeActorBindings = new Map();
+    constructor(socket, backendSessionRoutingId, messageSerializers, nativeSessionService, meshCompletions, publicSessionId = streamSessionIdFromRoutingId(backendSessionRoutingId), nativeSessionRouteForMesh) {
+        this.socket = socket;
+        this.backendSessionRoutingId = backendSessionRoutingId;
+        this.messageSerializers = messageSerializers;
+        this.nativeSessionService = nativeSessionService;
+        this.meshCompletions = meshCompletions;
+        this.publicSessionId = publicSessionId;
+        this.nativeSessionRouteForMesh = nativeSessionRouteForMesh;
+    }
+    get sessionId() {
+        return this.publicSessionId;
+    }
+    get routingId() {
+        return this.publicSessionId;
+    }
+    get actorBindingRoutingId() {
+        return this.backendSessionRoutingId;
+    }
+    actorBindingGeneration(actorId) {
+        return this.nativeActorBindings.get(actorId)?.bindingGeneration;
+    }
+    isTransportClosed() {
+        return this.transportClosed;
+    }
+    get localAddr() {
+        return this.currentLocalAddr;
+    }
+    get remoteAddr() {
+        return this.currentRemoteAddr;
+    }
+    write(payload, flags) {
+        const message = (0, payload_codec_1.encodeFrameworkPayloadMessage)(payload, this.messageSerializers);
+        try {
+            return this.socket.send(this.backendRoutingId(), message, flags ?? 0);
+        }
+        finally {
+            message.close();
+        }
+    }
+    writeRaw(payload, flags) {
+        return this.socket.send(this.backendRoutingId(), payload, flags ?? 0);
+    }
+    async submitRaw(payload, signal, timeoutMs) {
+        try {
+            (0, abort_1.throwIfAborted)(signal);
+            await this.socket.submit(this.backendRoutingId(), payload, timeoutMs);
+            return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+        }
+        catch (error) {
+            if ((0, runtime_values_1.isBackendNotConnectedError)(error))
+                return { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
+            throw error;
+        }
+    }
+    async submitBoundActor(actorId, parts, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        return await this.sendBoundActor(actorId, parts, ZLINK_SEND_DONT_WAIT)
+            ? { status: submission_result_1.ZLinkSubmitStatus.Submitted }
+            : { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
+    }
+    async close(signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        this.markTransportClosed();
+        this.socket.disconnectPeer(this.backendRoutingId());
+    }
+    async closeForDrain(signal) {
+        await this.closeForReason(protocol_1.ZLinkStreamCloseReasonCode.ServerDrain, 'server drain', signal);
+    }
+    async writeControl(name) {
+        const control = runtime_message_1.ZLinkBufferMessage.from((0, protocol_1.encodeStreamControlFrame)(name));
+        try {
+            await this.socket.submit(this.backendRoutingId(), control);
+        }
+        finally {
+            control.close();
+        }
+    }
+    async closeForReason(reason, diagnostic, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        this.markTransportClosed();
+        const closing = runtime_message_1.ZLinkBufferMessage.from((0, protocol_1.encodeSessionClosingFrame)(diagnostic, reason));
+        try {
+            await this.socket.submit(this.backendRoutingId(), closing);
+        }
+        finally {
+            closing.close();
+        }
+        this.socket.disconnectPeer(this.backendRoutingId());
+    }
+    async bindActor(actor, timeoutMs, signal, onBindingReplaced, authorityFence) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (this.transportClosed) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
+        }
+        const route = this.nativeRoute(actor.meshName);
+        if (route !== undefined) {
+            if (route.service.status().state === 1) {
+                route.service.start();
+            }
+            const nativeActor = toNativeActorRef(actor);
+            await this.ensureNativeActorRoute(route, actor, timeoutMs, signal);
+            if (this.isTransportClosed()) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
+            }
+            await this.requireSuccessfulCompletion(route.completions.submit(() => route.service.bindActor(this.backendRoutingId(), nativeActor, timeoutMs, onBindingReplaced === undefined
+                ? undefined
+                : (_actorId, retiredSession, replacedActor) => {
+                    onBindingReplaced(replacedActor, retiredSession);
+                }, toStreamSessionActorAuthorityFence(authorityFence)), signal), `Actor '${actor.actorId}' native session bind`);
+            const binding = route.service.bindings(this.backendRoutingId())
+                .find((candidate) => candidate.actor.actorId === nativeActor.actorId
+                && candidate.actor.generation === nativeActor.generation);
+            if (binding === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Actor '${actor.actorId}' native session bind completed without a binding snapshot.`);
+            }
+            if (this.isTransportClosed()) {
+                try {
+                    await this.requireSuccessfulCompletion(route.completions.submit(() => route.service.unbindActor(this.backendRoutingId(), nativeActor, binding.bindingGeneration, timeoutMs), signal), `Actor '${actor.actorId}' native session unbind`, IDEMPOTENT_UNBIND_TERMINAL_RESULTS);
+                }
+                catch (error) {
+                    if (this.hasNativeBinding(route, actor.actorId, binding.bindingGeneration)) {
+                        throw error;
+                    }
+                }
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
+            }
+            this.nativeActorBindings.set(actor.actorId, {
+                actor: nativeActor,
+                bindingGeneration: binding.bindingGeneration,
+                route
+            });
+            return;
+        }
+        await this.socket.bindActor(this.backendRoutingId(), toBackendActorRef(actor), timeoutMs, signal);
+    }
+    async ensureNativeActorRoute(route, actor, timeoutMs, signal) {
+        const completion = await route.completions.submit(() => route.service.lookupActor(actor.nodeRid, actor.actorId, timeoutMs), signal);
+        try {
+            const resolved = completion.kindData?.kind === 'actorLookupCompletion'
+                ? completion.kindData.location.actor
+                : undefined;
+            if (completion.terminalResult !== 0
+                || completion.failureErrno !== 0
+                || resolved === undefined
+                || resolved.actorId !== actor.actorId
+                || resolved.generation !== actor.objectGeneration
+                || String(resolved.nodeRid) !== String(actor.nodeRid)) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.actorId}' native route fence does not match its ActorRef `
+                    + `(expected ${String(actor.nodeRid)}/${actor.objectGeneration}, `
+                    + `resolved ${resolved === undefined ? 'none' : `${String(resolved.nodeRid)}/${resolved.generation}`}, `
+                    + `terminal=${completion.terminalResult}, failure=${completion.failureErrno}).`);
+            }
+        }
+        finally {
+            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+        }
+    }
+    async unbindActor(actorId, timeoutMs, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (this.transportClosed) {
+            // The native stream session is released by transport teardown. Do not
+            // submit a second unbind for a stale binding during reconnect cleanup.
+            this.nativeActorBindings.delete(actorId);
+            return;
+        }
+        const binding = this.nativeActorBindings.get(actorId);
+        if (binding?.route !== undefined) {
+            const route = binding.route;
+            if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+                this.nativeActorBindings.delete(actorId);
+                return;
+            }
+            try {
+                await this.requireSuccessfulCompletion(route.completions.submit(() => route.service.unbindActor(this.backendRoutingId(), binding.actor, binding.bindingGeneration, timeoutMs), signal), `Actor '${actorId}' native session unbind`, 
+                // Destroy can remove the actor registry entry before the old
+                // session owner processes its cleanup. Both a disconnected route and
+                // that stale actor route are idempotent unbind outcomes.
+                IDEMPOTENT_UNBIND_TERMINAL_RESULTS);
+            }
+            catch (error) {
+                // The service removes its local delivery before sending a remote
+                // tombstone. A transport teardown can therefore report an internal
+                // completion after the exact binding is already gone. Treat only that
+                // exact missing binding as stale cleanup; preserve other failures.
+                if (this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+                    throw error;
+                }
+            }
+            if (this.nativeActorBindings.get(actorId) === binding) {
+                this.nativeActorBindings.delete(actorId);
+            }
+            return;
+        }
+        await this.socket.unbindActor(this.backendRoutingId(), actorId, timeoutMs, signal);
+    }
+    async sendBoundActor(actorId, parts, flags) {
+        if (this.transportClosed) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
+        }
+        const binding = this.nativeActorBindings.get(actorId);
+        if (binding?.route !== undefined) {
+            const nativeParts = parts.map((part) => runtime_message_1.ZLinkBufferMessage.from(part.data()));
+            try {
+                return await binding.route.service.sendToActor(this.backendRoutingId(), binding.actor, nativeParts, { flags: flags ?? 0 }) === 0;
+            }
+            finally {
+                for (const part of nativeParts) {
+                    part.close();
+                }
+            }
+        }
+        return this.socket.sendBoundActor(this.backendRoutingId(), actorId, parts, flags ?? 0);
+    }
+    updateAddresses(localAddr, remoteAddr) {
+        this.currentLocalAddr = localAddr;
+        this.currentRemoteAddr = remoteAddr;
+    }
+    /** @internal Marks transport teardown before asynchronous lifecycle cleanup begins. */
+    markTransportClosed() {
+        this.transportClosed = true;
+    }
+    hasNativeBinding(route, actorId, bindingGeneration) {
+        try {
+            return route.service.bindings(this.backendRoutingId()).some(candidate => candidate.actor.actorId === actorId
+                && candidate.bindingGeneration === bindingGeneration);
+        }
+        catch {
+            // A closed native service owns the teardown state. Keep the original
+            // error when its binding snapshot is unavailable.
+            return true;
+        }
+    }
+    backendRoutingId() {
+        return this.backendSessionRoutingId;
+    }
+    async requireSuccessfulCompletion(completionPromise, operationName, acceptedTerminalResults = NO_ACCEPTED_TERMINAL_RESULTS) {
+        const completion = await completionPromise;
+        try {
+            if (completion.terminalResult !== 0
+                && !acceptedTerminalResults.has(completion.terminalResult)) {
+                throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`);
+            }
+        }
+        finally {
+            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+        }
+    }
+    nativeRoute(meshName) {
+        return this.nativeSessionRouteForMesh?.(meshName)
+            ?? (this.nativeSessionService !== undefined && this.meshCompletions !== undefined
+                ? {
+                    service: this.nativeSessionService,
+                    completions: this.meshCompletions
+                }
+                : undefined);
+    }
+}
+exports.ZLinkManagedStream = ZLinkManagedStream;
+function streamSessionIdFromRoutingId(routingId) {
+    if (typeof routingId === 'string') {
+        return routingId;
+    }
+    if (typeof routingId === 'object'
+        && routingId !== null
+        && 'toHex' in routingId
+        && typeof routingId.toHex === 'function') {
+        return routingId.toHex();
+    }
+    if (typeof routingId === 'object'
+        && routingId !== null
+        && 'toString' in routingId
+        && typeof routingId.toString === 'function') {
+        return routingId.toString();
+    }
+    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, 'Stream session routing id is invalid.');
+}
+function toBackendActorRef(actor) {
+    return {
+        nodeRid: actor.nodeRid,
+        actorId: actor.actorId,
+        generation: actor.objectGeneration
+    };
+}
+function toNativeActorRef(actor) {
+    return {
+        nodeRid: actor.nodeRid,
+        actorId: actor.actorId,
+        generation: actor.objectGeneration
+    };
+}
+function toStreamSessionActorAuthorityFence(fence) {
+    if (fence?.ownerNodeGeneration === undefined)
+        return undefined;
+    return {
+        targetNodeGeneration: fence.ownerNodeGeneration,
+        authorityOwnerGeneration: fence.authorityOwnerGeneration,
+        ownerLeaseGeneration: fence.ownerLeaseGeneration
+    };
+}

package/dist/runtime/streams/native-fallback-bound-session.d.ts

@@ -0,0 +1,24 @@
+import type { ActorRef, ZLinkBoundSession, ZLinkBoundSessionSendCall } from '../../contracts';
+import { type ZLinkActorRoutedJoinTransport, type ZLinkRemoteActorPacketTarget, type ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkNativeFallbackBoundSessionPort } from './stream-binding-runtime-ports';
+import type { ZLinkBackendActorSessionNode } from '../backend';
+export interface ZLinkNativeFallbackBoundSessionOptions {
+    readonly runtime: ZLinkNativeFallbackBoundSessionPort;
+    readonly routedTransport: ZLinkActorRoutedJoinTransport;
+    readonly actorRefProvider: () => ActorRef | undefined;
+    readonly nativeActorNodeProvider: () => ZLinkBackendActorSessionNode | undefined;
+    readonly localActorProvider?: () => boolean;
+    readonly remoteBoundSessionTargetProvider: () => ZLinkRemoteBoundSessionTarget | undefined;
+    readonly remoteActorPacketTargetProvider: () => ZLinkRemoteActorPacketTarget | undefined;
+    readonly requestTimeoutMs?: number;
+    readonly actorId: string;
+    readonly onSend?: (actorId: string, packetName: string) => void;
+    readonly reportError: (error: unknown) => void;
+    readonly flowCreationEnabled?: () => boolean;
+}
+export declare class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
+    private readonly options;
+    constructor(options: ZLinkNativeFallbackBoundSessionOptions);
+    send(message: unknown): ZLinkBoundSessionSendCall;
+    disconnect(signal?: AbortSignal): Promise<void>;
+}

package/dist/runtime/streams/native-fallback-bound-session.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkNativeFallbackBoundSession = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const submission_result_1 = require("../messaging/submission-result");
+const actors_1 = require("../actors");
+const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
+const bound_session_wire_1 = require("../actors/bound-session-wire");
+const actor_routed_json_request_1 = require("../actors/actor-routed-json-request");
+const protocol_1 = require("./protocol");
+const abort_1 = require("../abort");
+const packet_name_1 = require("../messaging/packet-name");
+const flow_context_1 = require("../diagnostics/flow-context");
+class ZLinkNativeFallbackBoundSession {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    send(message) {
+        return new ZLinkNativeFallbackBoundSessionSendCall(this.options, message);
+    }
+    async disconnect(signal) {
+        const remoteTarget = this.options.remoteBoundSessionTargetProvider();
+        if (remoteTarget !== undefined) {
+            const spotKind = 'spotKind' in remoteTarget ? remoteTarget.spotKind : undefined;
+            const payload = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+                actorId: this.options.actorId,
+                routerChannelId: remoteTarget.routerChannelId,
+                header: (0, protocol_1.encodeStreamHeader)(disconnectedFrameHeader()),
+                payload: Buffer.alloc(0)
+            });
+            const target = {
+                routerChannelId: remoteTarget.routerChannelId,
+                targetNodeRid: remoteTarget.targetNodeRid,
+                spotId: remoteTarget.spotId,
+                spotKind: spotKind ?? contracts_1.ZLinkSpotKind.Entry
+            };
+            if (await (0, actor_routed_json_request_1.tryRequestRoutedJson)(this.options.routedTransport, target, payload, { timeoutMs: this.options.requestTimeoutMs, signal })) {
+                return;
+            }
+            await this.options.routedTransport.sendToSpot(target, payload, { packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, signal });
+            return;
+        }
+        const actorRef = this.options.actorRefProvider();
+        const node = this.options.nativeActorNodeProvider();
+        if (actorRef !== undefined
+            && node !== undefined
+            && currentBindingGeneration(actorRef) !== undefined) {
+            await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
+            return;
+        }
+        await this.options.runtime.disconnectBoundSession(this.options.actorId, signal);
+    }
+}
+exports.ZLinkNativeFallbackBoundSession = ZLinkNativeFallbackBoundSession;
+class ZLinkNativeFallbackBoundSessionSendCall {
+    options;
+    message;
+    selectedPacketName;
+    selectedMetadata = new Map();
+    executed = false;
+    constructor(options, message) {
+        this.options = options;
+        this.message = message;
+    }
+    metadata(key, value) {
+        this.selectedMetadata.set(key, value);
+        return this;
+    }
+    packetName(packetName) {
+        this.selectedPacketName = packetName;
+        return this;
+    }
+    async submit(signal) {
+        if (this.executed) {
+            (0, submission_result_1.throwAlreadySubmitted)('Bound session send call');
+        }
+        const packetName = (0, packet_name_1.resolveFrameworkPacketName)(this.message, this.selectedPacketName, 'Bound session');
+        this.executed = true;
+        (0, abort_1.throwIfAborted)(signal);
+        const result = await this.execute(packetName, signal);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'Bound session send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound);
+    }
+    execute(packetName, signal) {
+        // Call-scoped flow (spec 27 §4): the relay JSON flow pair and any nested
+        // routed-transport envelope share one ambient flow that does not outlive
+        // this submit call.
+        return (0, flow_context_1.runWithOutboundFlow)(this.options.flowCreationEnabled?.() ?? true, () => this.executeScoped(packetName, signal));
+    }
+    async executeScoped(packetName, signal) {
+        const localActor = this.options.localActorProvider?.() === true;
+        const remoteTarget = this.options.remoteBoundSessionTargetProvider();
+        const sealedRemoteTarget = remoteTarget?.relocationSealId !== undefined;
+        let nativeAttempted = false;
+        if (localActor && !sealedRemoteTarget) {
+            const result = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata, signal);
+            if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+                this.traceSubmitted(result, packetName);
+                return result;
+            }
+            // A local Actor with a concrete native owner has a direct binding path.
+            // Use that path before a routed transfer target. The transfer target is
+            // retained for actors whose current owner is remote or whose native
+            // binding is no longer available.
+            const actorRef = this.options.actorRefProvider();
+            const node = this.options.nativeActorNodeProvider();
+            const bindingGeneration = currentBindingGeneration(actorRef);
+            if (actorRef !== undefined
+                && node !== undefined
+                && bindingGeneration !== undefined) {
+                nativeAttempted = true;
+                const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata, signal);
+                if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+                    this.traceSubmitted(result, packetName);
+                    return result;
+                }
+                if (remoteTarget === undefined) {
+                    return result;
+                }
+            }
+        }
+        if (remoteTarget !== undefined) {
+            const actorRef = this.options.actorRefProvider();
+            const ownershipGeneration = actorRef
+                ?.ownershipGeneration;
+            const payload = (0, bound_session_wire_1.encodeRemoteBoundSessionSendPayload)({
+                actorId: this.options.actorId,
+                actorMeshName: actorRef?.meshName,
+                actorNodeRid: actorRef === undefined ? undefined : String(actorRef.nodeRid),
+                actorNodeRidHex: actorRef?.nodeRid?.toHex?.(),
+                actorGeneration: actorRef?.objectGeneration.toString(),
+                actorOwnershipGeneration: ownershipGeneration?.toString(),
+                relocationSealId: remoteTarget.relocationSealId,
+                message: this.message,
+                boundPacketName: packetName,
+                metadata: this.selectedMetadata,
+                actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.options.remoteActorPacketTargetProvider()),
+                ...((this.options.flowCreationEnabled?.() ?? true)
+                    ? (0, flow_context_1.currentOrCreateFlow)('Application')
+                    : undefined)
+            });
+            const submit = this.options.routedTransport.submitInfrastructure
+                ?? this.options.routedTransport.submit;
+            const result = submit === undefined
+                ? await this.options.routedTransport.sendToSpot({
+                    routerChannelId: remoteTarget.routerChannelId,
+                    targetNodeRid: remoteTarget.targetNodeRid,
+                    spotId: remoteTarget.spotId,
+                    spotKind: contracts_1.ZLinkSpotKind.Entry
+                }, payload, { packetName: actors_1.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, signal })
+                : await submit.call(this.options.routedTransport, remoteTarget.routerChannelId, String(remoteTarget.targetNodeRid), actors_1.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, payload, signal);
+            this.traceSubmitted(result, packetName);
+            return result;
+        }
+        const localResult = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata, signal);
+        if (localResult.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+            this.traceSubmitted(localResult, packetName);
+            return localResult;
+        }
+        const actorRef = this.options.actorRefProvider();
+        const node = this.options.nativeActorNodeProvider();
+        const bindingGeneration = currentBindingGeneration(actorRef);
+        if (!nativeAttempted
+            && actorRef !== undefined
+            && node !== undefined
+            && bindingGeneration !== undefined) {
+            const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata, signal);
+            this.traceSubmitted(result, packetName);
+            return result;
+        }
+        if (localActor) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `No current session binding exists for actor '${this.options.actorId}'.`, true);
+        }
+        const result = await this.options.runtime.sendBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata, signal);
+        this.traceSubmitted(result, packetName);
+        return result;
+    }
+    traceSubmitted(result, packetName) {
+        if (result.status === submission_result_1.ZLinkSubmitStatus.Submitted) {
+            this.options.onSend?.(this.options.actorId, packetName);
+        }
+    }
+}
+function currentBindingGeneration(actorRef) {
+    const generation = actorRef
+        ?.bindingGeneration;
+    return positiveBindingGeneration(generation);
+}
+function positiveBindingGeneration(generation) {
+    return generation !== undefined && generation > 0n ? generation : undefined;
+}
+function disconnectedFrameHeader() {
+    return {
+        kind: protocol_1.ZLinkStreamMessageKind.Send,
+        codec: protocol_1.ZLinkStreamCodec.Raw,
+        flags: protocol_1.ZLinkStreamHeaderFlags.None,
+        name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+        metadata: new Map()
+    };
+}

package/dist/runtime/streams/protocol.d.ts

@@ -0,0 +1,67 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkFlowOrigin } from '../../contracts';
+export { utf8Decode, utf8Encode } from '@zlink-systems/stream-wire';
+export declare enum ZLinkStreamCodec {
+    Raw = 0,
+    Json = 1,
+    MessagePack = 2,
+    Protobuf = 3
+}
+export declare function streamCodecContentType(codec: ZLinkStreamCodec): string;
+export declare function streamCodecForContentType(contentType: string): ZLinkStreamCodec;
+export declare enum ZLinkStreamMessageKind {
+    Send = 1,
+    Request = 2,
+    Response = 3,
+    Error = 4,
+    Control = 5
+}
+export declare enum ZLinkStreamHeaderFlags {
+    None = 0,
+    HasRequestSeq = 1,
+    HasMetadata = 2,
+    PayloadCompressed = 4,
+    HasCorrelationId = 8,
+    HasFlowId = 16
+}
+export declare enum ZLinkStreamCloseReasonCode {
+    ClientClose = 1,
+    IdleTimeout = 2,
+    HeartbeatTimeout = 3,
+    ServerDrain = 4,
+    ProtocolError = 5,
+    TransportError = 6
+}
+export declare const ZLINK_STREAM_HEARTBEAT_PING = "$zlink.heartbeat.ping";
+export declare const ZLINK_STREAM_HEARTBEAT_PONG = "$zlink.heartbeat.pong";
+export interface ZLinkStreamFrameHeader {
+    readonly kind: ZLinkStreamMessageKind;
+    readonly codec: ZLinkStreamCodec;
+    readonly flags: ZLinkStreamHeaderFlags;
+    readonly requestSeq?: bigint;
+    readonly name: string;
+    readonly metadata: ReadonlyMap<string, string>;
+    readonly correlationId?: string;
+    readonly flowId?: string;
+    readonly flowOrigin?: ZLinkFlowOrigin;
+}
+export type ZLinkStreamReplyMessageKind = ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error;
+export interface ZLinkStreamFrame {
+    readonly header: Uint8Array;
+    readonly payload: Uint8Array;
+}
+export declare function resolvePacketName(message: unknown, explicitPacketName: string | undefined): string;
+export declare function ensureSingleSubmit(executed: boolean): void;
+export declare function encodeStreamFrame(header: ZLinkStreamFrameHeader, payload: Uint8Array): Uint8Array;
+export declare function encodeStreamControlFrame(name: string): Uint8Array;
+export declare function encodeSessionClosingFrame(diagnostic?: string, reason?: ZLinkStreamCloseReasonCode): Uint8Array;
+export declare function decodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame;
+export declare function tryDecodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame | undefined;
+export declare function encodeStreamHeader(header: ZLinkStreamFrameHeader): Uint8Array;
+export declare function decodeStreamHeader(header: Uint8Array, flowEnabled?: boolean): ZLinkStreamFrameHeader;
+export declare function actorRequestDeadlineMetadata(deadlineUnixMs: number | undefined): ReadonlyMap<string, string>;
+export declare function decodeActorRequestDeadlineUnixMs(header: Uint8Array): number | undefined;
+export declare function createStreamReplyHeader(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, codec: ZLinkStreamCodec, flags: ZLinkStreamHeaderFlags, metadata: ReadonlyMap<string, string>, includeFlow?: boolean): ZLinkStreamFrameHeader;
+export declare function messageToBytes(message: Message): Uint8Array;
+export declare function lz4Pickle(payload: Uint8Array): Uint8Array;
+export declare function lz4Unpickle(payload: Uint8Array, maxDecompressedSize?: number): Uint8Array;