@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/backend/node/node-backend-adapter-support.js

@@ -3,24 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.zlink = void 0;
 exports.isBindingNotFound = isBindingNotFound;
 exports.isRouteRecvRetryable = isRouteRecvRetryable;
-exports.isPollerInterruptedError = isPollerInterruptedError;
 exports.submitBindingPublish = submitBindingPublish;
 exports.submitBindingReply = submitBindingReply;
 exports.submitBindingAsyncSend = submitBindingAsyncSend;
 exports.submitBindingSyncSend = submitBindingSyncSend;
 exports.submitBindingRequest = submitBindingRequest;
-exports.closeWithBusyRetry = closeWithBusyRetry;
+exports.closeBindingHandle = closeBindingHandle;
 exports.isContextTerminatedError = isContextTerminatedError;
 exports.disableSocketLinger = disableSocketLinger;
 exports.toNativeRoutingId = toNativeRoutingId;
 exports.translateBindingResultError = translateBindingResultError;
 exports.toNativeActorRef = toNativeActorRef;
+const node_os_1 = require("node:os");
+const submission_result_1 = require("../../messaging/submission-result");
 const node_backend_adapter_1 = require("../node-backend-adapter");
 const runtime_values_1 = require("../runtime-values");
-const submission_result_1 = require("../../messaging/submission-result");
+const nativeErrnoValues = node_os_1.constants.errno;
 exports.zlink = (0, node_backend_adapter_1.loadBinding)();
 function isBindingNotFound(error) {
-    return error instanceof exports.zlink.ConfigError && error.result === exports.zlink.ConfigResult.NotFound;
+    return error instanceof exports.zlink.ConnectError && error.result === exports.zlink.ConnectResult.NotFound;
 }
 function isNonBlockingRecvEmpty(error) {
     return error instanceof exports.zlink.RecvError && error.result === exports.zlink.RecvResult.NoData;
@@ -32,11 +33,9 @@ function isRouteRecvRetryable(error) {
                 error.result === exports.zlink.RecvResult.InvalidHandle) &&
             isNativeBadAddress(error)));
 }
-function isPollerInterruptedError(error) {
-    return error instanceof exports.zlink.RecvError && error.nativeErrno === 4;
-}
 function isNativeBadAddress(error) {
-    return error.nativeErrno === 14 || /Bad address/i.test(String(error.message ?? ''));
+    return (error.nativeErrno === nativeErrnoValues.EFAULT ||
+        /Bad address/i.test(String(error.message ?? '')));
 }
 function submitBindingPublish(operation, payload) {
     try {
@@ -126,36 +125,28 @@ async function submitBindingRequest(operation, payload, timeoutMs) {
         throw translateBindingResultError(error);
     }
 }
-async function closeWithBusyRetry(target) {
-    let lastError;
-    for (let attempt = 0; attempt < 8; attempt++) {
-        try {
-            target.close();
-            return;
-        }
-        catch (error) {
-            if (isSuccessfulOrAlreadyShutdownCloseError(error)) {
-                return;
-            }
-            if (!isBusyCloseError(error)) {
-                throw error;
-            }
-            lastError = error;
-            await new Promise((resolve) => setImmediate(resolve));
-        }
+/**
+ * Closes a binding handle once. An already closed or terminated handle counts as
+ * closed. A busy close propagates to the caller.
+ */
+function closeBindingHandle(target) {
+    try {
+        target.close();
+    }
+    catch (error) {
+        if (!isSuccessfulOrAlreadyShutdownCloseError(error))
+            throw error;
     }
-    throw lastError;
-}
-function isBusyCloseError(error) {
-    return (error instanceof Error &&
-        'code' in error &&
-        [401, 404].includes(error.code));
 }
 function isSuccessfulOrAlreadyShutdownCloseError(error) {
     return (isContextTerminatedError(error) ||
         (error instanceof Error &&
             'code' in error &&
-            [0, 402, 403].includes(error.code)));
+            [
+                exports.zlink.CloseResult.Ok,
+                exports.zlink.CloseResult.Shutdown,
+                exports.zlink.CloseResult.InvalidHandle
+            ].includes(error.code)));
 }
 function isContextTerminatedError(error) {
     return error instanceof Error && /context was terminated/i.test(error.message);
@@ -198,9 +189,12 @@ function toNativeMessageLike(message) {
     }
     return message;
 }
-function translateBindingResultError(error) {
+function translateBindingResultError(error, phase = 'completion') {
     if (error instanceof exports.zlink.SubmitError) {
-        return new runtime_values_1.ZLinkBackendResultError('submit', error.result, error.nativeErrno, { cause: error });
+        return new runtime_values_1.ZLinkBackendResultError('submit', error.result, error.nativeErrno, {
+            cause: error,
+            phase
+        });
     }
     if (error instanceof exports.zlink.RequestError) {
         return new runtime_values_1.ZLinkBackendResultError('request', error.result, error.nativeErrno, {

package/dist/runtime/backend/node/node-event-loop-poller.d.ts

@@ -9,8 +9,8 @@ export declare class ZLinkNodeEventLoopPoller {
     private readonly events;
     private readableHandler;
     private disposed;
-    constructor(socket: Socket, pollCompletion: boolean, readableHandler: () => void);
-    setReadableHandler(handler: () => void): void;
+    constructor(socket: Socket, pollCompletion: boolean, readableHandler: (receiveReady: boolean, routeReady: boolean) => void, pollRoute?: boolean);
+    setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void;
     dispose(): void;
     private readonly onReady;
 }

package/dist/runtime/backend/node/node-event-loop-poller.js

@@ -12,12 +12,16 @@ class ZLinkNodeEventLoopPoller {
     events = node_backend_adapter_support_1.zlink.createPollEvents(1);
     readableHandler;
     disposed = false;
-    constructor(socket, pollCompletion, readableHandler) {
+    constructor(socket, pollCompletion, readableHandler, pollRoute = false) {
         this.readableHandler = readableHandler;
         try {
             const pollEvents = [node_backend_adapter_support_1.zlink.PollEventFlag.PollIn];
             if (pollCompletion)
                 pollEvents.push(node_backend_adapter_support_1.zlink.PollEventFlag.PollCompletion);
+            // A ROUTER selected-route change (Core ROUTER §10.1) wakes the same
+            // handler, whose owner is the socket's one route observer.
+            if (pollRoute)
+                pollEvents.push(node_backend_adapter_support_1.zlink.PollEventFlag.PollRoute);
             this.poller.add(socket, pollEvents, 0);
             socket.setReadableHandler(this.onReady);
         }
@@ -33,17 +37,18 @@ class ZLinkNodeEventLoopPoller {
     dispose() {
         if (this.disposed)
             return;
-        this.disposed = true;
-        this.events.close();
         this.poller.close();
+        this.events.close();
+        this.disposed = true;
     }
     onReady = () => {
         if (this.disposed)
             return;
         const ready = this.poller.wait(this.events, 0);
-        if (ready === 0 || this.events.hasEvent(0, node_backend_adapter_support_1.zlink.PollEventFlag.PollIn)) {
-            this.readableHandler();
-        }
+        const receiveReady = ready === 0 || this.events.hasEvent(0, node_backend_adapter_support_1.zlink.PollEventFlag.PollIn);
+        const routeReady = ready > 0 && this.events.hasEvent(0, node_backend_adapter_support_1.zlink.PollEventFlag.PollRoute);
+        if (receiveReady || routeReady)
+            this.readableHandler(receiveReady, routeReady);
     };
 }
 exports.ZLinkNodeEventLoopPoller = ZLinkNodeEventLoopPoller;

package/dist/runtime/backend/node/node-monitor-backend-adapter.js

@@ -30,6 +30,7 @@ function wrapMonitorSocket(nativeInstance) {
 function toBackendMonitorEvent(event) {
     return {
         nativeEvent: event.event,
+        readyEdge: (event.flags & node_backend_adapter_support_1.zlink.MonitorEventFlag.ConnectionReadyEdge) !== 0,
         routingId: event.routingId ?? undefined,
         localAddr: event.localAddr,
         remoteAddr: event.remoteAddr,

package/dist/runtime/backend/node/node-raw-binding-port.d.ts

@@ -1,6 +1,6 @@
 import { type Context } from '@zlink-systems/zlink';
 import type { ZLinkRawBindingPort, ZLinkRawHostPort } from '../raw-binding-port';
-export type { ZLinkRawBindingPort, ZLinkRawDealerPort, ZLinkRawHostPort, ZLinkRawMonitorPort, ZLinkRawMonitorRecord, ZLinkRawReceivedRecord, ZLinkRawRouterPort, ZLinkRawSocketPort } from '../raw-binding-port';
+export type { ZLinkRawBindingPort, ZLinkRawDealerPort, ZLinkRawHostPort, ZLinkRawMonitorPort, ZLinkRawMonitorRecord, ZLinkRawReceivedRecord, ZLinkRawRouterPort, ZLinkRawRouterRoute, ZLinkRawSocketPort } from '../raw-binding-port';
 export declare class ZLinkNodeRawBindingPort implements ZLinkRawBindingPort {
     private readonly sharedContext?;
     private readonly routerReceiveTimeoutMs?;

package/dist/runtime/backend/node/node-raw-binding-port.js

@@ -48,15 +48,16 @@ class NodeRawHostPort {
             return;
         this.state = 'stopping';
         const failures = [];
-        for (const resource of this.resources.splice(0).reverse()) {
+        for (const resource of [...this.resources].reverse()) {
             try {
                 resource.close();
+                this.resources.splice(this.resources.indexOf(resource), 1);
             }
             catch (error) {
                 failures.push(error);
             }
         }
-        if (this.ownsContext) {
+        if (this.ownsContext && failures.length === 0) {
             try {
                 this.context.close();
             }
@@ -64,10 +65,10 @@ class NodeRawHostPort {
                 failures.push(error);
             }
         }
-        this.state = 'closed';
         if (failures.length > 0) {
             throw new AggregateError(failures, 'Raw binding host cleanup failed.');
         }
+        this.state = 'closed';
     }
     own(resource) {
         this.resources.push(resource);
@@ -85,9 +86,9 @@ class NodeRawSocketPort {
     monitors = new Set();
     eventLoopPoller;
     closed = false;
-    constructor(socket) {
+    constructor(socket, pollRoute = false) {
         this.socket = socket;
-        this.eventLoopPoller = new node_event_loop_poller_1.ZLinkNodeEventLoopPoller(socket, true, () => { });
+        this.eventLoopPoller = new node_event_loop_poller_1.ZLinkNodeEventLoopPoller(socket, true, () => { }, pollRoute);
     }
     setReadableHandler(handler) {
         this.requireOpen();
@@ -158,18 +159,17 @@ class NodeRawSocketPort {
                 failures.push(error);
             }
         }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'Raw socket cleanup failed.');
+        }
         this.endpoints.clear();
         try {
             this.socket.close();
         }
         catch (error) {
-            failures.push(error);
+            throw new AggregateError([error], 'Raw socket cleanup failed.');
         }
         this.closed = true;
-        if (failures.length > 0) {
-            console.error('Raw socket cleanup causes:', failures);
-            throw new AggregateError(failures, 'Raw socket cleanup failed.');
-        }
     }
     requireOpen() {
         if (this.closed)
@@ -183,7 +183,7 @@ class NodeRawRouterPort extends NodeRawSocketPort {
         this.socket.disconnectRid(bindingRoutingId(routingId));
     }
     constructor(socket, receiveTimeoutMs) {
-        super(socket);
+        super(socket, true);
         socket.options.handover = true;
         socket.options.mandatory = true;
         socket.options.probe = true;
@@ -213,16 +213,30 @@ class NodeRawRouterPort extends NodeRawSocketPort {
     }
     async request(targetRid, parts, timeoutMs) {
         this.requireOpen();
+        let submission;
         try {
-            const replies = await appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
+            submission = appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
                 .timeout(timeoutMs)
-                .submit().reply;
+                .submit();
+        }
+        catch (error) {
+            throw (0, node_backend_adapter_support_1.translateBindingResultError)(error, 'submit');
+        }
+        try {
+            const replies = await requestReply(submission);
             return copyAndClose(replies);
         }
         catch (error) {
-            throw (0, node_backend_adapter_support_1.translateBindingResultError)(error);
+            throw (0, node_backend_adapter_support_1.translateBindingResultError)(error, 'completion');
         }
     }
+    routesSnapshot() {
+        this.requireOpen();
+        return this.socket.routesSnapshot().map((route) => ({
+            routingId: route.routingId.toString(),
+            routeGeneration: route.routeGeneration
+        }));
+    }
     receive(dontWait = false) {
         this.requireOpen();
         return receiveRecord(this.socket, dontWait, () => {
@@ -252,16 +266,33 @@ class NodeRawDealerPort extends NodeRawSocketPort {
     }
     async request(parts, timeoutMs) {
         this.requireOpen();
-        const replies = await appendRequestParts(this.socket.request(), parts)
-            .timeout(timeoutMs)
-            .submit().reply;
-        return copyAndClose(replies);
+        let submission;
+        try {
+            submission = appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit();
+        }
+        catch (error) {
+            throw (0, node_backend_adapter_support_1.translateBindingResultError)(error, 'submit');
+        }
+        try {
+            const replies = await requestReply(submission);
+            return copyAndClose(replies);
+        }
+        catch (error) {
+            throw (0, node_backend_adapter_support_1.translateBindingResultError)(error, 'completion');
+        }
     }
     receive(dontWait = false) {
         this.requireOpen();
         return receiveRecord(this.socket, dontWait);
     }
 }
+async function requestReply(submission) {
+    if (submission.result === zlink_1.SubmitResult.Backpressured) {
+        const [, replies] = await Promise.all([submission.admitted, submission.reply]);
+        return replies;
+    }
+    return submission.reply;
+}
 class NodeRawMonitorPort {
     monitor;
     release;
@@ -290,9 +321,9 @@ class NodeRawMonitorPort {
     close() {
         if (this.closed)
             return;
+        this.monitor.close();
         this.closed = true;
         this.release();
-        this.monitor.close();
     }
 }
 function appendSendParts(operation, parts) {
@@ -344,6 +375,7 @@ function receiveRecord(socket, dontWait, nextRequestSequence, reply) {
         return {
             sourceRid,
             sourceRoute,
+            routeGeneration: received.routeGeneration,
             ...(requestSeq === undefined ? {} : { requestSeq }),
             ...(receivedReply === undefined
                 ? {}

package/dist/runtime/backend/node/node-raw-mesh-backend.d.ts

@@ -1,18 +1,18 @@
 import { SubmitResult, type RequestResult as RequestResultValue, type SubmitResult as SubmitResultValue } from '@zlink-systems/zlink';
-import { type ZLinkBackendMessageLike as MessageLike } from '../runtime-values';
+import { type RoutingId } from '../../../contracts';
+import type { ApplicationJobQueuePort } from '../../application-jobs/contracts';
 import type { ZLinkDispatchErrorReporter } from '../../channels/dispatch-error-reporter';
-import type { MeshOperationId, MeshPeerEntry, MeshPublisher, ReadyBatch, ReadyRecord, ReceiveBatch, ServiceSpot, StreamSessionService } from '../../foundation/service-runtime-contracts';
 import { type RawServiceRequestResult } from '../../foundation/raw-service-mesh-runtime';
-import { type ServiceApplicationPayload } from '../../foundation/service-wire-m6a-codec';
-import { type ServiceAsyncInstanceActivationAuthority, type ServiceInstanceApplicationLifecycle, type ServicePendingInstanceActivation, type ServiceSpotMessageFollowSeal, type ServiceUserSpotOperationHandler, type ServiceUserSpotOperationResult } from '../../foundation/service-stateful-runtime';
+import type { ServiceInstanceActivationRecoveryEnvelope } from '../../foundation/service-instance-activation-recovery-codec';
+import { type MeshOperationId, type MeshPeerEntry, type MeshPublisher, type ReadyBatch, type ReadyRecord, type ReceiveBatch, type ServiceSpot, type StreamSessionService, MeshNodeRuntimeState } from '../../foundation/service-runtime-contracts';
 import type { ServiceActorRef, ServiceSpotState } from '../../foundation/service-stateful-registry';
+import { type ServiceAsyncInstanceActivationAuthority, type ServiceInstanceApplicationLifecycle, type ServicePendingInstanceActivation, type ServiceSpotMessageFollowSeal, type ServiceUserSpotOperationHandler, type ServiceUserSpotOperationResult } from '../../foundation/service-stateful-runtime';
 import type { ServiceActorCreateRecord, ServiceDirectSpotRouteFence, ServiceInstanceActivationTarget, ServiceInstanceRouteFence, ServiceSpotRouteFence, ServiceUserSpotCloseRecord, ServiceUserSpotCreateRecord } from '../../foundation/service-stateful-wire-codec';
-import type { ServiceInstanceActivationRecoveryEnvelope } from '../../foundation/service-instance-activation-recovery-codec';
 import type { ServiceNodeDescriptor } from '../../foundation/service-topology-registry';
-import type { RoutingId } from '../../../contracts';
-import type { ZLinkBackendActorRef, ZLinkBackendActorSessionSendFence, ZLinkBackendObjectPlacement, ZLinkBackendMeshNode } from '../contracts';
+import { type ServiceApplicationPayload } from '../../foundation/service-wire-m6a-codec';
+import type { ZLinkBackendActorRef, ZLinkBackendMeshNode, ZLinkBackendObjectPlacement } from '../contracts';
 import type { ZLinkRawBindingPort } from '../raw-binding-port';
-import type { ApplicationJobQueuePort } from '../../application-jobs/contracts';
+import { type ZLinkBackendMessageLike as MessageLike } from '../runtime-values';
 /**
  * M6A MeshNode backend. Stateful Spot/Actor entry points stay explicit until
  * their owning M6B runtime is connected; topology and node/channel dispatch do
@@ -42,6 +42,7 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     private readable;
     private readonly onReadable;
     private readonly onMaintenance;
+    private readonly onPendingOperationsChanged;
     private nextPeerIntent;
     private closed;
     private objectRole;
@@ -128,7 +129,7 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         readonly timeoutMs?: number;
     }): MeshOperationId;
     status(): {
-        state: number;
+        state: MeshNodeRuntimeState;
         routingId: RoutingId;
         meshName: string;
         localEndpoint: string;
@@ -172,7 +173,7 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     restoreUserSpotAuthority(spotId: string, stableType: string, generation: bigint, authorityOwnerGeneration: bigint): ServiceSpot;
     restoreSpotAuthority(spotId: string, objectKind: 'user_spot' | 'instance_spot', stableType: string, generation: bigint, authorityOwnerGeneration: bigint): ServiceSpot;
     createActor(actorId: string): ZLinkBackendActorRef;
-    restoreActorAuthority(actorId: string, stableType: string, generation: bigint, authorityOwnerGeneration: bigint, spotId: string, spotGeneration: bigint, membershipEpoch: bigint): ZLinkBackendActorRef;
+    restoreActorAuthority(actorId: string, stableType: string, generation: bigint, authorityOwnerGeneration: bigint, spotId: string | undefined, spotGeneration: bigint, membershipEpoch: bigint): ZLinkBackendActorRef;
     discardRelocatedActor(actor: ZLinkBackendActorRef): void;
     restoreActorSessionBinding(actor: ZLinkBackendActorRef, sessionNodeRid: unknown, sessionRid: unknown, bindingGeneration: bigint): void;
     registerInstanceIntent(instanceType: string, route: ServiceInstanceRouteFence, expectedCurrentRoute?: ServiceInstanceRouteFence | null): void;
@@ -193,8 +194,8 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     abortSpotMessageFollowIngress(seal: ServiceSpotMessageFollowSeal): boolean;
     commitSpotMessageFollowIngress(seal: ServiceSpotMessageFollowSeal, target: ServiceDirectSpotRouteFence, durationMs: number): Promise<boolean>;
     forgetSpotRoute(spot: ServiceSpotRouteFence['spot'], authorityOwnerGeneration: bigint, storeVersion?: string): void;
-    sendToInstanceSpot(route: ServiceInstanceRouteFence, parts: MessageLike | readonly MessageLike[], sourceSpotId?: string, metadata?: ReadonlyMap<string, string>): Promise<SubmitResult>;
-    requestInstanceSpot(route: ServiceInstanceRouteFence, parts: MessageLike | readonly MessageLike[], timeoutMs?: number, sourceSpotId?: string, metadata?: ReadonlyMap<string, string>): MeshOperationId;
+    sendToInstanceSpot(route: ServiceInstanceRouteFence, parts: MessageLike | readonly MessageLike[], sourceSpotId?: string, metadata?: ReadonlyMap<string, string>, instanceIntent?: boolean): Promise<SubmitResult>;
+    requestInstanceSpot(route: ServiceInstanceRouteFence, parts: MessageLike | readonly MessageLike[], timeoutMs?: number, sourceSpotId?: string, metadata?: ReadonlyMap<string, string>, instanceIntent?: boolean): MeshOperationId;
     actorLookup(actorId: string): {
         actor: ServiceActorRef;
         spotId: string;
@@ -229,7 +230,7 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     actorRequestToActor(source: ZLinkBackendActorRef, target: ZLinkBackendActorRef, parts: MessageLike | readonly MessageLike[], options?: {
         readonly timeoutMs?: number;
     }): MeshOperationId;
-    sendActorBoundSession(actor: ZLinkBackendActorRef, expectedBindingGeneration: bigint, parts: MessageLike | readonly MessageLike[], _flags?: number, actorFence?: ZLinkBackendActorSessionSendFence): Promise<SubmitResultValue>;
+    sendActorBoundSession(actor: ZLinkBackendActorRef, expectedBindingGeneration: bigint, parts: MessageLike | readonly MessageLike[], _flags?: number): Promise<SubmitResultValue>;
     closeActorBoundSession(actor: ZLinkBackendActorRef, expectedBindingGeneration: bigint, timeoutMs?: number): MeshOperationId;
     leaveActor(actor: ZLinkBackendActorRef, expectedMembershipEpoch: bigint, timeoutMs?: number): MeshOperationId;
     createStreamSessionService(stream: unknown): StreamSessionService;
@@ -261,10 +262,11 @@ export declare class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     private requireNotStarted;
 }
 /**
- * Classifies a generic node/channel request rejection into a completion
- * terminal. Spec 32-framework-error-model:91-92 — a reply that could not be
- * decoded (ServiceWireProtocolError from the reply parser) is a protocol
- * failure, not connection loss; only genuine transport rejections collapse to
- * NotConnected.
+ * The one classification of a failed node/channel/stateful request into its
+ * completion terminal. A binding REQUEST result is Core's decision and is kept
+ * as is; a submit failure is classified from its submission or completion phase.
+ * A reply that could not be decoded is a protocol
+ * failure (spec 32-framework-error-model:91-92). The failure code is a wire
+ * code, so a Core result carries 0.
  */
-export declare function genericOperationFailure(error: unknown): RawServiceRequestResult;
+export declare function requestFailureResult(error: unknown): RawServiceRequestResult;