@zlink-systems/framework 0.10.0

package/dist/runtime/framework-errors-internal.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_FRAMEWORK_INTERNAL_ERROR_KIND_VALUES = exports.ZLinkFrameworkInternalErrorKind = void 0;
+exports.createInternalFrameworkException = createInternalFrameworkException;
+exports.internalFrameworkErrorKind = internalFrameworkErrorKind;
+exports.requestResultToPublicErrorKind = requestResultToPublicErrorKind;
+exports.wireReplyFailureException = wireReplyFailureException;
+exports.translateWireReplyDecodeError = translateWireReplyDecodeError;
+exports.internalFrameworkErrorCode = internalFrameworkErrorCode;
+exports.internalFrameworkWireReply = internalFrameworkWireReply;
+exports.internalFrameworkErrorKindFromWireFailureCode = internalFrameworkErrorKindFromWireFailureCode;
+exports.internalFrameworkErrorKindFromWireReply = internalFrameworkErrorKindFromWireReply;
+exports.isCanonicalWireReplyTerminal = isCanonicalWireReplyTerminal;
+const ZLinkFrameworkException_1 = require("../contracts/Errors/ZLinkFrameworkException");
+const runtime_values_1 = require("./backend/runtime-values");
+const service_wire_m6a_codec_1 = require("./foundation/service-wire-m6a-codec");
+/** Detailed failure reasons owned by Framework runtime bounded contexts. */
+var ZLinkFrameworkInternalErrorKind;
+(function (ZLinkFrameworkInternalErrorKind) {
+    ZLinkFrameworkInternalErrorKind["ActorRouteNotFound"] = "actorRouteNotFound";
+    ZLinkFrameworkInternalErrorKind["ActorCreateFailed"] = "actorCreateFailed";
+    ZLinkFrameworkInternalErrorKind["ActorAlreadyExists"] = "actorAlreadyExists";
+    ZLinkFrameworkInternalErrorKind["ActorTypeMismatch"] = "actorTypeMismatch";
+    ZLinkFrameworkInternalErrorKind["SpotCreateFailed"] = "spotCreateFailed";
+    ZLinkFrameworkInternalErrorKind["SpotRouteNotFound"] = "spotRouteNotFound";
+    ZLinkFrameworkInternalErrorKind["SpotTypeMismatch"] = "spotTypeMismatch";
+    ZLinkFrameworkInternalErrorKind["ActorSessionNotBound"] = "actorSessionNotBound";
+    ZLinkFrameworkInternalErrorKind["HandlerNotFound"] = "handlerNotFound";
+    ZLinkFrameworkInternalErrorKind["RouteHandlerNotFound"] = "routeHandlerNotFound";
+    ZLinkFrameworkInternalErrorKind["ActorDispatchHandlerNotFound"] = "actorDispatchHandlerNotFound";
+    ZLinkFrameworkInternalErrorKind["PayloadDecodeFailed"] = "payloadDecodeFailed";
+    ZLinkFrameworkInternalErrorKind["RouteNotConnected"] = "routeNotConnected";
+    ZLinkFrameworkInternalErrorKind["RequestTargetNotFound"] = "requestTargetNotFound";
+    ZLinkFrameworkInternalErrorKind["RequestRejected"] = "requestRejected";
+    ZLinkFrameworkInternalErrorKind["RequestProtocolError"] = "requestProtocolError";
+    ZLinkFrameworkInternalErrorKind["RequestFailed"] = "requestFailed";
+    ZLinkFrameworkInternalErrorKind["WorkerQueueFull"] = "workerQueueFull";
+    ZLinkFrameworkInternalErrorKind["WorkerTimedOut"] = "workerTimedOut";
+    ZLinkFrameworkInternalErrorKind["WorkerFailed"] = "workerFailed";
+    ZLinkFrameworkInternalErrorKind["ActorLocationStale"] = "actorLocationStale";
+    ZLinkFrameworkInternalErrorKind["ActorCreateRejected"] = "actorCreateRejected";
+    ZLinkFrameworkInternalErrorKind["ObjectClientNotConfigured"] = "objectClientNotConfigured";
+    ZLinkFrameworkInternalErrorKind["MeshSelectionRequired"] = "meshSelectionRequired";
+    ZLinkFrameworkInternalErrorKind["MeshNotFound"] = "meshNotFound";
+    ZLinkFrameworkInternalErrorKind["InvalidConfiguration"] = "invalidConfiguration";
+    ZLinkFrameworkInternalErrorKind["AlreadySubmitted"] = "alreadySubmitted";
+    ZLinkFrameworkInternalErrorKind["ActorGenerationStale"] = "actorGenerationStale";
+    ZLinkFrameworkInternalErrorKind["ActorMoving"] = "actorMoving";
+    ZLinkFrameworkInternalErrorKind["DeadlineExceeded"] = "deadlineExceeded";
+    ZLinkFrameworkInternalErrorKind["PlacementCapacityExhausted"] = "placementCapacityExhausted";
+    ZLinkFrameworkInternalErrorKind["RoutingIdConflict"] = "routingIdConflict";
+    ZLinkFrameworkInternalErrorKind["SpotGenerationStale"] = "spotGenerationStale";
+    ZLinkFrameworkInternalErrorKind["SpotMoving"] = "spotMoving";
+    ZLinkFrameworkInternalErrorKind["RelocationDataLost"] = "relocationDataLost";
+    ZLinkFrameworkInternalErrorKind["SpotIdConflict"] = "spotIdConflict";
+    ZLinkFrameworkInternalErrorKind["RuntimeShutdown"] = "runtimeShutdown";
+    ZLinkFrameworkInternalErrorKind["RelocationDisabled"] = "relocationDisabled";
+    ZLinkFrameworkInternalErrorKind["RelocationTargetUnavailable"] = "relocationTargetUnavailable";
+    ZLinkFrameworkInternalErrorKind["RelocationFailed"] = "relocationFailed";
+    ZLinkFrameworkInternalErrorKind["InvalidOperation"] = "invalidOperation";
+    ZLinkFrameworkInternalErrorKind["ActorRouteUnavailable"] = "actorRouteUnavailable";
+})(ZLinkFrameworkInternalErrorKind || (exports.ZLinkFrameworkInternalErrorKind = ZLinkFrameworkInternalErrorKind = {}));
+const INTERNAL_TO_PUBLIC = Object.freeze({
+    [ZLinkFrameworkInternalErrorKind.ActorRouteNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.ActorCreateFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure,
+    [ZLinkFrameworkInternalErrorKind.ActorAlreadyExists]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.AlreadyExists,
+    [ZLinkFrameworkInternalErrorKind.ActorTypeMismatch]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.TypeMismatch,
+    [ZLinkFrameworkInternalErrorKind.SpotCreateFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure,
+    [ZLinkFrameworkInternalErrorKind.SpotRouteNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.SpotTypeMismatch]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.TypeMismatch,
+    [ZLinkFrameworkInternalErrorKind.ActorSessionNotBound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation,
+    [ZLinkFrameworkInternalErrorKind.HandlerNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.RouteHandlerNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ProtocolError,
+    [ZLinkFrameworkInternalErrorKind.RouteNotConnected]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable,
+    [ZLinkFrameworkInternalErrorKind.RequestTargetNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.RequestRejected]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Rejected,
+    [ZLinkFrameworkInternalErrorKind.RequestProtocolError]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ProtocolError,
+    [ZLinkFrameworkInternalErrorKind.RequestFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure,
+    [ZLinkFrameworkInternalErrorKind.WorkerQueueFull]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.CapacityExceeded,
+    [ZLinkFrameworkInternalErrorKind.WorkerTimedOut]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.DeadlineExceeded,
+    [ZLinkFrameworkInternalErrorKind.WorkerFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure,
+    [ZLinkFrameworkInternalErrorKind.ActorLocationStale]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable,
+    [ZLinkFrameworkInternalErrorKind.ActorCreateRejected]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Rejected,
+    [ZLinkFrameworkInternalErrorKind.ObjectClientNotConfigured]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotConfigured,
+    [ZLinkFrameworkInternalErrorKind.MeshSelectionRequired]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotConfigured,
+    [ZLinkFrameworkInternalErrorKind.MeshNotFound]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound,
+    [ZLinkFrameworkInternalErrorKind.InvalidConfiguration]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotConfigured,
+    [ZLinkFrameworkInternalErrorKind.AlreadySubmitted]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation,
+    [ZLinkFrameworkInternalErrorKind.ActorGenerationStale]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation,
+    [ZLinkFrameworkInternalErrorKind.ActorMoving]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable,
+    [ZLinkFrameworkInternalErrorKind.DeadlineExceeded]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.DeadlineExceeded,
+    [ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.CapacityExceeded,
+    [ZLinkFrameworkInternalErrorKind.RoutingIdConflict]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.AlreadyExists,
+    [ZLinkFrameworkInternalErrorKind.SpotGenerationStale]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation,
+    [ZLinkFrameworkInternalErrorKind.SpotMoving]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable,
+    [ZLinkFrameworkInternalErrorKind.RelocationDataLost]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.DataLost,
+    [ZLinkFrameworkInternalErrorKind.SpotIdConflict]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.AlreadyExists,
+    [ZLinkFrameworkInternalErrorKind.RuntimeShutdown]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ShuttingDown,
+    [ZLinkFrameworkInternalErrorKind.RelocationDisabled]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Rejected,
+    [ZLinkFrameworkInternalErrorKind.RelocationTargetUnavailable]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable,
+    [ZLinkFrameworkInternalErrorKind.RelocationFailed]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure,
+    [ZLinkFrameworkInternalErrorKind.InvalidOperation]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation,
+    [ZLinkFrameworkInternalErrorKind.ActorRouteUnavailable]: ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable
+});
+exports.ZLINK_FRAMEWORK_INTERNAL_ERROR_KIND_VALUES = Object.freeze({
+    [ZLinkFrameworkInternalErrorKind.ActorRouteNotFound]: 0,
+    [ZLinkFrameworkInternalErrorKind.ActorCreateFailed]: 1,
+    [ZLinkFrameworkInternalErrorKind.ActorAlreadyExists]: 2,
+    [ZLinkFrameworkInternalErrorKind.ActorTypeMismatch]: 3,
+    [ZLinkFrameworkInternalErrorKind.SpotCreateFailed]: 4,
+    [ZLinkFrameworkInternalErrorKind.SpotRouteNotFound]: 5,
+    [ZLinkFrameworkInternalErrorKind.SpotTypeMismatch]: 6,
+    [ZLinkFrameworkInternalErrorKind.ActorSessionNotBound]: 7,
+    [ZLinkFrameworkInternalErrorKind.HandlerNotFound]: 8,
+    [ZLinkFrameworkInternalErrorKind.RouteHandlerNotFound]: 9,
+    [ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound]: 10,
+    [ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed]: 11,
+    [ZLinkFrameworkInternalErrorKind.RouteNotConnected]: 12,
+    [ZLinkFrameworkInternalErrorKind.RequestTargetNotFound]: 13,
+    [ZLinkFrameworkInternalErrorKind.RequestRejected]: 14,
+    [ZLinkFrameworkInternalErrorKind.RequestProtocolError]: 15,
+    [ZLinkFrameworkInternalErrorKind.RequestFailed]: 16,
+    [ZLinkFrameworkInternalErrorKind.WorkerQueueFull]: 17,
+    [ZLinkFrameworkInternalErrorKind.WorkerTimedOut]: 18,
+    [ZLinkFrameworkInternalErrorKind.WorkerFailed]: 19,
+    [ZLinkFrameworkInternalErrorKind.ActorLocationStale]: 20,
+    [ZLinkFrameworkInternalErrorKind.ActorCreateRejected]: 21,
+    [ZLinkFrameworkInternalErrorKind.ObjectClientNotConfigured]: 22,
+    [ZLinkFrameworkInternalErrorKind.MeshSelectionRequired]: 23,
+    [ZLinkFrameworkInternalErrorKind.MeshNotFound]: 24,
+    [ZLinkFrameworkInternalErrorKind.InvalidConfiguration]: 25,
+    [ZLinkFrameworkInternalErrorKind.AlreadySubmitted]: 26,
+    [ZLinkFrameworkInternalErrorKind.ActorGenerationStale]: 27,
+    [ZLinkFrameworkInternalErrorKind.ActorMoving]: 28,
+    [ZLinkFrameworkInternalErrorKind.DeadlineExceeded]: 29,
+    [ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted]: 30,
+    [ZLinkFrameworkInternalErrorKind.RoutingIdConflict]: 31,
+    [ZLinkFrameworkInternalErrorKind.SpotGenerationStale]: 32,
+    [ZLinkFrameworkInternalErrorKind.SpotMoving]: 33,
+    [ZLinkFrameworkInternalErrorKind.RelocationDataLost]: 34,
+    [ZLinkFrameworkInternalErrorKind.SpotIdConflict]: 35,
+    [ZLinkFrameworkInternalErrorKind.RuntimeShutdown]: 36,
+    [ZLinkFrameworkInternalErrorKind.RelocationDisabled]: 37,
+    [ZLinkFrameworkInternalErrorKind.RelocationTargetUnavailable]: 38,
+    [ZLinkFrameworkInternalErrorKind.RelocationFailed]: 39,
+    [ZLinkFrameworkInternalErrorKind.InvalidOperation]: 40,
+    [ZLinkFrameworkInternalErrorKind.ActorRouteUnavailable]: 41
+});
+const INTERNAL_KIND_BY_WIRE_FAILURE_CODE = new Map([
+    ...Object.entries(exports.ZLINK_FRAMEWORK_INTERNAL_ERROR_KIND_VALUES)
+        .map(([kind, code]) => [code + 1, kind]),
+    //  Spec 32-framework-error-model:99-103 — a workerQueueFull(18) received in a
+    //  remote reply is the target's queue state (Unavailable), not the source-owned
+    //  CapacityExceeded that the wire-value-minus-one derivation would give.
+    [18, ZLinkFrameworkInternalErrorKind.RouteNotConnected]
+]);
+const WIRE_TERMINAL_RESULT_BY_FAILURE_CODE = new Map([
+    ...[1, 6, 8, 9, 10, 11, 14].map(code => [code, 102]),
+    ...[2, 5, 13, 17, 19, 20, 35, 42].map(code => [code, 105]),
+    ...[3, 4, 7, 21, 33, 34].map(code => [code, 107]),
+    ...[12, 16].map(code => [code, 104]),
+    ...[15, 18, 22].map(code => [code, 106])
+]);
+const INTERNAL_KIND = new WeakMap();
+function createInternalFrameworkException(kind, message, causeOrRetry, cause) {
+    const error = new ZLinkFrameworkException_1.ZLinkFrameworkException(INTERNAL_TO_PUBLIC[kind], message, typeof causeOrRetry === 'boolean' ? cause : causeOrRetry);
+    INTERNAL_KIND.set(error, kind);
+    return error;
+}
+function internalFrameworkErrorKind(error) {
+    return INTERNAL_KIND.get(error);
+}
+/**
+ * Maps a backend request terminal (RequestResult) to the public framework
+ * error kind. Mirrors the authoritative C++ request_failure_mapper /
+ * Java ZLinkBackendRequestResult.toFrameworkErrorKind so a client-side request
+ * terminal is classified identically across languages instead of collapsing to
+ * Unavailable. Spec 32-framework-error-model:81-92 (request-terminal
+ * classification); a deadline yields DeadlineExceeded, a lost route Unavailable.
+ * Backpressure on the REQUEST path is CapacityExceeded (distinct from the
+ * one-way submit path, which is DeadlineExceeded).
+ */
+function requestResultToPublicErrorKind(result) {
+    switch (result) {
+        case runtime_values_1.RequestResult.TimedOut:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.DeadlineExceeded;
+        case runtime_values_1.RequestResult.NotFound:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound;
+        case runtime_values_1.RequestResult.Terminated:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ShuttingDown;
+        case runtime_values_1.RequestResult.ProtocolError:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ProtocolError;
+        case runtime_values_1.RequestResult.Rejected:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Rejected;
+        case runtime_values_1.RequestResult.Backpressured:
+            //  Source-owned send/completion reservation exhausted (spec 32:93-98).
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.CapacityExceeded;
+        case runtime_values_1.RequestResult.Conflict:
+        case runtime_values_1.RequestResult.Busy:
+        case runtime_values_1.RequestResult.NotConnected:
+            //  Spec 32:99-103 — a remote target's queue/owner state (conflict, busy,
+            //  or lost connection) is a resource this runtime does not own: Unavailable.
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable;
+        case runtime_values_1.RequestResult.InvalidArgument:
+        case runtime_values_1.RequestResult.InvalidState:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InvalidOperation;
+        case runtime_values_1.RequestResult.InternalError:
+        case runtime_values_1.RequestResult.NotSupported:
+        default:
+            return ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.InternalFailure;
+    }
+}
+/**
+ * Ownership-aware classification of a remote reply/completion terminal plus its
+ * fine failure code into a public framework exception (spec
+ * 32-framework-error-model:81-118, 99-108). A fine failure code refines the
+ * coarse terminal; when absent (0) or unrecognised, the coarse terminal
+ * classifies. Remote another-node queue/operation-table saturation
+ * (Conflict/Busy) is Unavailable — a resource this runtime does not own — while
+ * only the placement admission terminal Backpressured(113) is CapacityExceeded,
+ * a target-owned admission decision rather than a queue. Shared by the lifecycle
+ * completion paths (Actor join, User Spot create/close) so they classify
+ * identically to the request path instead of collapsing to a single kind.
+ */
+function wireReplyFailureException(terminalResult, failureErrno, message) {
+    if (failureErrno !== 0) {
+        const fine = internalFrameworkErrorKindFromWireFailureCode(failureErrno);
+        if (fine !== undefined) {
+            return createInternalFrameworkException(fine, message);
+        }
+    }
+    if (terminalResult === runtime_values_1.RequestResult.Backpressured) {
+        return createInternalFrameworkException(ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, message);
+    }
+    return new ZLinkFrameworkException_1.ZLinkFrameworkException(requestResultToPublicErrorKind(terminalResult), message);
+}
+/**
+ * Translates a wire decode/shape failure raised while awaiting a remote
+ * lifecycle reply into the public ProtocolError classification.
+ * ServiceWireProtocolError is a plain Error thrown by the wire codec when a
+ * reply cannot be processed; spec 32-framework-error-model:58-60 and 91-92
+ * require the awaiting caller to observe a Framework ProtocolError instead of
+ * an untyped transport error. Every other error is returned unchanged so
+ * already-classified failures keep their kind.
+ */
+function translateWireReplyDecodeError(error) {
+    if (error instanceof service_wire_m6a_codec_1.ServiceWireProtocolError) {
+        return createInternalFrameworkException(ZLinkFrameworkInternalErrorKind.RequestProtocolError, error.message);
+    }
+    return error;
+}
+function internalFrameworkErrorCode(error) {
+    const kind = INTERNAL_KIND.get(error);
+    return kind === undefined ? error.kind : exports.ZLINK_FRAMEWORK_INTERNAL_ERROR_KIND_VALUES[kind];
+}
+/** Produces the canonical stateful wire terminal without leaking internal kinds. */
+function internalFrameworkWireReply(error) {
+    const kind = INTERNAL_KIND.get(error);
+    if (kind === ZLinkFrameworkInternalErrorKind.DeadlineExceeded) {
+        return { terminalResult: 101, failureCode: 0 };
+    }
+    if (kind === undefined) {
+        return { terminalResult: 105, failureCode: 17 };
+    }
+    const failureCode = exports.ZLINK_FRAMEWORK_INTERNAL_ERROR_KIND_VALUES[kind] + 1;
+    const terminalResult = WIRE_TERMINAL_RESULT_BY_FAILURE_CODE.get(failureCode);
+    return terminalResult === undefined
+        ? { terminalResult: 105, failureCode: 17 }
+        : { terminalResult, failureCode };
+}
+/** Decodes the stateful reply failureCode convention without exposing wire offsets to callers. */
+function internalFrameworkErrorKindFromWireFailureCode(failureCode) {
+    return INTERNAL_KIND_BY_WIRE_FAILURE_CODE.get(failureCode);
+}
+/** Restores a typed failure only when its wire terminal result is canonical. */
+function internalFrameworkErrorKindFromWireReply(terminalResult, failureCode) {
+    // ServiceStaleGenerationError is emitted as NotFound with the historical
+    // stale-route code, while the same internal code is also used by Conflict
+    // replies from the actor route protocol.
+    if (terminalResult === 102 && failureCode === 21) {
+        return ZLinkFrameworkInternalErrorKind.ActorLocationStale;
+    }
+    const kind = internalFrameworkErrorKindFromWireFailureCode(failureCode);
+    if (kind === undefined)
+        return undefined;
+    const expectedTerminalResult = WIRE_TERMINAL_RESULT_BY_FAILURE_CODE.get(failureCode);
+    return expectedTerminalResult === terminalResult ? kind : undefined;
+}
+const BOUNDARY_WIRE_TERMINAL_RESULTS = new Set([
+    101, 103, 108, 109, 110, 111, 112, 113
+]);
+/** Checks the terminal and failure-code pair before a transport maps it. */
+function isCanonicalWireReplyTerminal(terminalResult, failureCode) {
+    if (terminalResult === 0)
+        return failureCode === 0;
+    if (BOUNDARY_WIRE_TERMINAL_RESULTS.has(terminalResult))
+        return failureCode === 0;
+    return internalFrameworkErrorKindFromWireReply(terminalResult, failureCode) !== undefined;
+}

package/dist/runtime/handlers/handler-instance-scope.d.ts

@@ -0,0 +1,11 @@
+import type { Type, ZLinkMessageContext } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+export interface ZLinkHandlerInstanceScope {
+    resolve<T>(type: Type<T>): Promise<T>;
+    dispose(): Promise<void>;
+}
+export declare function runInHandlerInstanceScope<T>(providerResolver: ZLinkProviderResolver | undefined, context: ZLinkMessageContext | undefined, callback: (scope: ZLinkHandlerInstanceScope) => Promise<T>): Promise<T>;
+export declare function resolveLifecycleHandler<T>(owner: object, type: Type<T>, providerResolver?: ZLinkProviderResolver): Promise<T>;
+export declare function runWithLifecycleHandler<THandler, TResult>(owner: object, type: Type<THandler>, providerResolver: ZLinkProviderResolver | undefined, callback: (handler: THandler) => Promise<TResult>): Promise<TResult>;
+export declare function disposeLifecycleHandlers(owner: object): Promise<void>;
+export declare function disposeOwnedInstance(instance: unknown): Promise<void>;

package/dist/runtime/handlers/handler-instance-scope.js

@@ -0,0 +1,284 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInHandlerInstanceScope = runInHandlerInstanceScope;
+exports.resolveLifecycleHandler = resolveLifecycleHandler;
+exports.runWithLifecycleHandler = runWithLifecycleHandler;
+exports.disposeLifecycleHandlers = disposeLifecycleHandlers;
+exports.disposeOwnedInstance = disposeOwnedInstance;
+const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("../execution/state-lane");
+const HANDLER_SCOPE_FACTORY = Symbol.for('@zlink-systems/framework.handler-instance-scope-factory');
+const activeHandlerScope = new node_async_hooks_1.AsyncLocalStorage();
+const activeLifecycleScope = new node_async_hooks_1.AsyncLocalStorage();
+const detachedStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:handler-instance-scope');
+const dispatchScopes = new WeakMap();
+const lifecycleScopes = new WeakMap();
+async function runInHandlerInstanceScope(providerResolver, context, callback) {
+    const active = activeHandlerScope.getStore();
+    if (active !== undefined) {
+        return callback(active.scope);
+    }
+    if (context !== undefined) {
+        const existing = dispatchScopes.get(context);
+        if (existing !== undefined) {
+            return callback(existing);
+        }
+    }
+    const scope = createHandlerInstanceScope(providerResolver, context);
+    if (context !== undefined) {
+        dispatchScopes.set(context, scope);
+    }
+    try {
+        return await activeHandlerScope.run({ scope }, () => callback(scope));
+    }
+    finally {
+        if (context !== undefined && dispatchScopes.get(context) === scope) {
+            dispatchScopes.delete(context);
+        }
+        await scope.dispose();
+    }
+}
+async function resolveLifecycleHandler(owner, type, providerResolver) {
+    let scope = lifecycleScopes.get(owner);
+    if (scope === undefined) {
+        scope = Promise.resolve(new LifecycleHandlerInstanceScope(createHandlerInstanceScope(providerResolver)));
+        lifecycleScopes.set(owner, scope);
+    }
+    return (await scope).resolve(type);
+}
+async function runWithLifecycleHandler(owner, type, providerResolver, callback) {
+    let scope = lifecycleScopes.get(owner);
+    if (scope === undefined) {
+        scope = Promise.resolve(new LifecycleHandlerInstanceScope(createHandlerInstanceScope(providerResolver)));
+        lifecycleScopes.set(owner, scope);
+    }
+    return (await scope).run(type, callback);
+}
+async function disposeLifecycleHandlers(owner) {
+    const scope = lifecycleScopes.get(owner);
+    if (scope === undefined)
+        return;
+    const resolved = await scope;
+    await resolved.dispose();
+    // Keep the closed scope as a tombstone for the lifetime of the owner object.
+    // A late dispatch must fail instead of creating a second activation.
+}
+function createHandlerInstanceScope(providerResolver, context) {
+    const factory = providerResolver === undefined
+        ? undefined
+        : providerResolver[HANDLER_SCOPE_FACTORY];
+    if (isHandlerInstanceScopeFactory(factory)) {
+        return factory.create(context);
+    }
+    return new DefaultHandlerInstanceScope(providerResolver);
+}
+function isHandlerInstanceScopeFactory(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.create === 'function';
+}
+class DefaultHandlerInstanceScope {
+    providerResolver;
+    lane = new state_lane_1.ZLinkStateLane();
+    instances = new Map();
+    owned = [];
+    disposed = false;
+    constructor(providerResolver) {
+        this.providerResolver = providerResolver;
+    }
+    async resolve(type) {
+        const resolution = await this.lane.run(() => this.resolveCore(type));
+        if (resolution.activation !== undefined) {
+            startOutsideStateLane(() => {
+                void this.activate(type, resolution.activation);
+            });
+        }
+        return await resolution.promise;
+    }
+    async dispose() {
+        const disposal = await this.lane.run(() => this.beginDisposeCore());
+        if (disposal === undefined)
+            return;
+        await Promise.allSettled(disposal.pending);
+        for (const instance of disposal.owned) {
+            await disposeOwnedInstance(instance);
+        }
+        await this.lane.run(() => this.completeDisposeCore());
+    }
+    resolveCore(type) {
+        if (this.disposed) {
+            throw new Error('Handler instance scope is already disposed.');
+        }
+        let instance = this.instances.get(type);
+        if (instance !== undefined)
+            return { promise: instance };
+        const activation = createDeferred();
+        instance = activation.promise;
+        this.instances.set(type, activation.promise);
+        return { promise: instance, activation };
+    }
+    beginDisposeCore() {
+        if (this.disposed)
+            return undefined;
+        this.disposed = true;
+        return {
+            pending: [...this.instances.values()],
+            owned: [...this.owned].reverse()
+        };
+    }
+    completeDisposeCore() {
+        this.owned.length = 0;
+        this.instances.clear();
+    }
+    async activate(type, activation) {
+        let instance;
+        try {
+            instance = await this.providerResolver?.create?.(type)
+                ?? new type();
+        }
+        catch (error) {
+            activation.reject(error);
+            return;
+        }
+        const accepted = await this.lane.run(() => this.acceptActivationCore(instance));
+        if (accepted) {
+            activation.resolve(instance);
+            return;
+        }
+        try {
+            await disposeOwnedInstance(instance);
+            activation.reject(new Error('Handler instance scope was disposed during activation.'));
+        }
+        catch (error) {
+            activation.reject(error);
+        }
+    }
+    acceptActivationCore(instance) {
+        if (this.disposed)
+            return false;
+        this.owned.push(instance);
+        return true;
+    }
+}
+class LifecycleHandlerInstanceScope {
+    instances;
+    lane = new state_lane_1.ZLinkStateLane();
+    activeInvocations = 0;
+    closing = false;
+    idle;
+    resolveIdle;
+    disposal;
+    constructor(instances) {
+        this.instances = instances;
+    }
+    async resolve(type) {
+        const resolution = await this.lane.run(() => ({ promise: this.resolveCore(type) }));
+        return await resolution.promise;
+    }
+    resolveCore(type) {
+        this.throwIfClosingCore();
+        return this.instances.resolve(type);
+    }
+    async run(type, callback) {
+        await this.lane.run(() => this.beginInvocationCore());
+        try {
+            return await activeLifecycleScope.run(this, async () => callback(await this.instances.resolve(type)));
+        }
+        finally {
+            await this.lane.run(() => this.completeInvocationCore());
+        }
+    }
+    async dispose() {
+        const disposeFromActiveInvocation = activeLifecycleScope.getStore() === this;
+        const disposal = await this.lane.run(() => this.beginDisposeCore());
+        if (disposal.deferred !== undefined) {
+            startOutsideStateLane(() => {
+                void this.disposeWhenIdle(disposal);
+            });
+        }
+        if (disposeFromActiveInvocation) {
+            // Waiting here would make the current handler wait for its own terminal
+            // completion. The same disposal promise continues after run() releases
+            // the final active invocation.
+            void disposal.completion.catch(() => undefined);
+            return;
+        }
+        await disposal.completion;
+    }
+    throwIfClosingCore() {
+        if (this.closing) {
+            throw new Error('Handler lifecycle scope is closing.');
+        }
+    }
+    beginInvocationCore() {
+        this.throwIfClosingCore();
+        this.activeInvocations += 1;
+    }
+    completeInvocationCore() {
+        this.activeInvocations -= 1;
+        if (this.activeInvocations === 0) {
+            this.resolveIdle?.();
+            this.resolveIdle = undefined;
+            this.idle = undefined;
+        }
+    }
+    beginDisposeCore() {
+        if (!this.closing) {
+            this.closing = true;
+            if (this.activeInvocations > 0) {
+                this.idle = new Promise((resolve) => {
+                    this.resolveIdle = resolve;
+                });
+            }
+        }
+        if (this.disposal !== undefined) {
+            return { completion: this.disposal, idle: undefined };
+        }
+        const deferred = createDeferred();
+        this.disposal = deferred.promise;
+        return { completion: deferred.promise, deferred, idle: this.idle };
+    }
+    async disposeWhenIdle(disposal) {
+        const deferred = disposal.deferred;
+        try {
+            await disposal.idle;
+            await this.instances.dispose();
+            deferred.resolve();
+        }
+        catch (error) {
+            await this.lane.run(() => this.failDisposalCore(deferred.promise));
+            deferred.reject(error);
+        }
+    }
+    failDisposalCore(completion) {
+        if (this.disposal === completion) {
+            this.disposal = undefined;
+        }
+    }
+}
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((complete, fail) => {
+        resolve = complete;
+        reject = fail;
+    });
+    return { promise, resolve, reject };
+}
+function startOutsideStateLane(work) {
+    return detachedStateLaneResource.runInAsyncScope(work);
+}
+async function disposeOwnedInstance(instance) {
+    if (instance === null || instance === undefined)
+        return;
+    const value = instance;
+    if (typeof value.dispose === 'function') {
+        await value.dispose();
+    }
+    else if (typeof value.close === 'function') {
+        await value.close();
+    }
+    else if (typeof value.onModuleDestroy === 'function') {
+        await value.onModuleDestroy();
+    }
+}

package/dist/runtime/handlers/index.d.ts

@@ -0,0 +1,13 @@
+import { type Type, type ZLinkHandlerFilterNext, type ZLinkHandlerFilter, type ZLinkHandlerFilterContext } from '../../contracts';
+import { type ZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
+export interface ZLinkHandlerDescriptor {
+    readonly handlerType: Type;
+    readonly metadata: ZLinkDecoratorMetadata;
+}
+export interface ZLinkHandlerExposurePolicy {
+    readonly handlerGroups?: readonly string[];
+    readonly explicitHandlers?: readonly Type[];
+}
+export declare function scanZLinkHandlerTypes(handlerTypes: readonly Type[]): readonly ZLinkHandlerDescriptor[];
+export declare function exposeZLinkHandlers(handlerTypes: readonly Type[], policy: ZLinkHandlerExposurePolicy): readonly ZLinkHandlerDescriptor[];
+export declare function invokeZLinkHandlerFilters(filters: readonly ZLinkHandlerFilter[], context: ZLinkHandlerFilterContext, terminal: ZLinkHandlerFilterNext, signal?: AbortSignal): Promise<boolean>;

package/dist/runtime/handlers/index.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanZLinkHandlerTypes = scanZLinkHandlerTypes;
+exports.exposeZLinkHandlers = exposeZLinkHandlers;
+exports.invokeZLinkHandlerFilters = invokeZLinkHandlerFilters;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const Attributes_1 = require("../../contracts/Handlers/Attributes");
+function scanZLinkHandlerTypes(handlerTypes) {
+    return handlerTypes.flatMap((handlerType) => (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType)
+        .filter((metadata) => metadata.kind !== 'handlerGroup' && metadata.kind !== 'packet')
+        .map((metadata) => ({ handlerType, metadata })));
+}
+function exposeZLinkHandlers(handlerTypes, policy) {
+    const explicit = new Set(policy.explicitHandlers ?? []);
+    const groups = new Set(policy.handlerGroups ?? []);
+    return scanZLinkHandlerTypes(handlerTypes).filter((descriptor) => {
+        if (explicit.has(descriptor.handlerType)) {
+            return true;
+        }
+        if (groups.size === 0) {
+            return false;
+        }
+        return (0, Attributes_1.readZLinkDecoratorMetadata)(descriptor.handlerType).some((metadata) => metadata.kind === 'handlerGroup' && metadata.groupName !== undefined && groups.has(metadata.groupName));
+    });
+}
+async function invokeZLinkHandlerFilters(filters, context, terminal, signal) {
+    if (filters.length === 0) {
+        //  Fast path for the dominant unfiltered dispatch: no chain closures and
+        //  no extra microtask hop per message.
+        await terminal();
+        return true;
+    }
+    let handlerInvoked = false;
+    let next = async () => {
+        handlerInvoked = true;
+        await terminal();
+    };
+    for (let index = filters.length - 1; index >= 0; index -= 1) {
+        const filter = filters[index];
+        const previous = invokeAtMostOnce(next);
+        next = async () => {
+            await filter.invoke(context, previous, signal);
+        };
+    }
+    await next();
+    return handlerInvoked;
+}
+function invokeAtMostOnce(next) {
+    let invoked = false;
+    return () => {
+        if (invoked) {
+            return Promise.reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'A handler filter cannot invoke next more than once.'));
+        }
+        invoked = true;
+        return next();
+    };
+}