@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/actors/actor-context.ts

@@ -1,4 +1,7 @@
-import { ZLinkFrameworkInternalErrorKind, createInternalFrameworkException  } from '../framework-errors-internal';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import type {
   RoutingId,
   SpotId,
@@ -10,11 +13,7 @@ import type {
   ZLinkBoundSession,
   ZLinkBoundSessionSendCall
 } from '../../contracts';
-import {
-  ZLinkEncodedPayload,
-  ZLinkFrameworkException,
-  ZLinkMessage
-} from '../../contracts';
+import { ZLinkEncodedPayload, ZLinkFrameworkException, ZLinkMessage } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import { type ZLinkMessageSerializer } from '../../contracts';
@@ -26,13 +25,8 @@ import {
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import {
-  encodeFrameworkPayloadMessage
-} from '../messaging/payload-codec';
-import {
-  ZLinkActorRuntimeState,
-  toFrameworkActorRef
-} from './actor-runtime-state';
+import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
+import { ZLinkActorRuntimeState, toFrameworkActorRef } from './actor-runtime-state';
 import type {
   ZLinkActorBoundSessionFactory,
   ZLinkActorJoinCoordinator
@@ -45,6 +39,7 @@ import {
 import { createRandomOperationIdentity } from '../foundation/operation-identity';
 import { deferActorJoin } from './actor-join-deferred-scope';
 import { captureZLinkSpotSerialTurn } from '../execution';
+import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
 
 export const ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = Symbol('zlink.actor.join-entry-spot-runtime');
 
@@ -140,14 +135,16 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
   ): Promise<boolean> {
     const requestMessage = encodeJoinRequest(request, this.messageSerializers);
     try {
-      return (await this.requireJoinCoordinator().joinEntrySpot(
-        this.requireActor(),
-        this.state,
-        nodeRid,
-        requestMessage,
-        undefined,
-        signal
-      )).accepted;
+      return (
+        await this.requireJoinCoordinator().joinEntrySpot(
+          this.requireActor(),
+          this.state,
+          nodeRid,
+          requestMessage,
+          undefined,
+          signal
+        )
+      ).accepted;
     } finally {
       requestMessage.close();
     }
@@ -180,8 +177,7 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
     private readonly spotId: SpotId,
     private readonly request: unknown,
     private readonly messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer> | undefined
-  ) {
-  }
+  ) {}
 
   timeout(timeoutMs: number): this {
     this.timeoutMs = validateJoinTimeout(timeoutMs);
@@ -209,7 +205,8 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
     const operationId = createJoinOperationId();
     let discarded = false;
     let prepared = false;
-    let pendingJoin: Promise<import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>> | undefined;
+    let pendingJoin:
+      Promise<import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>> | undefined;
     const discard = async (): Promise<void> => {
       if (discarded) return;
       discarded = true;
@@ -223,7 +220,6 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
     };
     try {
       deferActorJoin({
-        requestBytes: requestMessage.data().byteLength,
         prepare: async () => {
           if (prepared) return;
           prepared = true;
@@ -252,50 +248,53 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
         },
         discard,
         execute: async () => {
-        let result: import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>;
-        try {
-          const pending = pendingJoin ?? this.coordinator.joinSpot(
-            this.actor,
-            this.state,
-            this.spotId,
-            requestMessage,
-            remainingJoinTimeout(deadline.atMs),
-            deadline.signal,
-            operationId
-          );
-          result = this.turn === undefined
-            ? await pending
-            : await this.turn.yieldFrameworkPromise(pending);
-        } catch (error) {
-          this.state.endDeferredJoin();
-          await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId)
-            .catch(() => undefined);
-          await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
-          return;
-        } finally {
-          deadline.close();
-          requestMessage.close();
-        }
-        if (
-          !result.accepted
-          || sourceNodeRid === undefined
-          || result.actor === undefined
-          || String(sourceNodeRid) === String(result.actor.nodeRid)
-        ) {
-          await notifyJoinCompletion(
-            this.actor, operationId, result, this.messageSerializers);
-        } else {
-          result.reply?.close();
-        }
-        const finalization = result.finalizeDeferredJoin?.();
-        if (finalization !== undefined) {
-          // Releasing a rejected provisional handoff can enqueue source
-          // backlog behind this same Spot turn. Yield the lifecycle boundary
-          // so replay can run without overtaking the completion callback.
-          await (this.turn === undefined
-            ? finalization
-            : this.turn.yieldFrameworkPromise(finalization));
-        }
+          let result: import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>;
+          try {
+            const pending =
+              pendingJoin ??
+              this.coordinator.joinSpot(
+                this.actor,
+                this.state,
+                this.spotId,
+                requestMessage,
+                remainingJoinTimeout(deadline.atMs),
+                deadline.signal,
+                operationId
+              );
+            result =
+              this.turn === undefined
+                ? await pending
+                : await this.turn.yieldFrameworkPromise(pending);
+          } catch (error) {
+            this.state.endDeferredJoin();
+            await this.coordinator
+              .abortDeferredJoin?.(this.actor, this.state, operationId)
+              .catch(() => undefined);
+            await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
+            return;
+          } finally {
+            deadline.close();
+            requestMessage.close();
+          }
+          if (
+            !result.accepted ||
+            sourceNodeRid === undefined ||
+            result.actor === undefined ||
+            String(sourceNodeRid) === String(result.actor.nodeRid)
+          ) {
+            await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
+          } else {
+            result.reply?.close();
+          }
+          const finalization = result.finalizeDeferredJoin?.();
+          if (finalization !== undefined) {
+            // Releasing a rejected provisional handoff can enqueue source
+            // backlog behind this same Spot turn. Yield the lifecycle boundary
+            // so replay can run without overtaking the completion callback.
+            await (this.turn === undefined
+              ? finalization
+              : this.turn.yieldFrameworkPromise(finalization));
+          }
         }
       });
     } catch (error) {
@@ -316,8 +315,7 @@ class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall
     private readonly coordinator: ZLinkActorJoinCoordinator,
     private readonly request: unknown,
     private readonly messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer> | undefined
-  ) {
-  }
+  ) {}
 
   timeout(timeoutMs: number): this {
     this.timeoutMs = validateJoinTimeout(timeoutMs);
@@ -345,7 +343,8 @@ class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall
     const operationId = createJoinOperationId();
     let discarded = false;
     let prepared = false;
-    let pendingJoin: Promise<import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>> | undefined;
+    let pendingJoin:
+      Promise<import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>> | undefined;
     const discard = async (): Promise<void> => {
       if (discarded) return;
       discarded = true;
@@ -359,7 +358,6 @@ class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall
     };
     try {
       deferActorJoin({
-        requestBytes: requestMessage.data().byteLength,
         prepare: async () => {
           if (prepared) return;
           prepared = true;
@@ -385,47 +383,50 @@ class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall
         },
         discard,
         execute: async () => {
-        let result: import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>;
-        try {
-          const pending = pendingJoin ?? this.coordinator.joinEntrySpot(
-            this.actor,
-            this.state,
-            undefined,
-            requestMessage,
-            remainingJoinTimeout(deadline.atMs),
-            deadline.signal,
-            operationId
-          );
-          result = this.turn === undefined
-            ? await pending
-            : await this.turn.yieldFrameworkPromise(pending);
-        } catch (error) {
-          this.state.endDeferredJoin();
-          await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId)
-            .catch(() => undefined);
-          await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
-          return;
-        } finally {
-          deadline.close();
-          requestMessage.close();
-        }
-        if (
-          !result.accepted
-          || sourceNodeRid === undefined
-          || result.actor === undefined
-          || String(sourceNodeRid) === String(result.actor.nodeRid)
-        ) {
-          await notifyJoinCompletion(
-            this.actor, operationId, result, this.messageSerializers);
-        } else {
-          result.reply?.close();
-        }
-        const finalization = result.finalizeDeferredJoin?.();
-        if (finalization !== undefined) {
-          await (this.turn === undefined
-            ? finalization
-            : this.turn.yieldFrameworkPromise(finalization));
-        }
+          let result: import('./actor-runtime-contracts').ZLinkActorJoinRuntimeResult<Message>;
+          try {
+            const pending =
+              pendingJoin ??
+              this.coordinator.joinEntrySpot(
+                this.actor,
+                this.state,
+                undefined,
+                requestMessage,
+                remainingJoinTimeout(deadline.atMs),
+                deadline.signal,
+                operationId
+              );
+            result =
+              this.turn === undefined
+                ? await pending
+                : await this.turn.yieldFrameworkPromise(pending);
+          } catch (error) {
+            this.state.endDeferredJoin();
+            await this.coordinator
+              .abortDeferredJoin?.(this.actor, this.state, operationId)
+              .catch(() => undefined);
+            await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
+            return;
+          } finally {
+            deadline.close();
+            requestMessage.close();
+          }
+          if (
+            !result.accepted ||
+            sourceNodeRid === undefined ||
+            result.actor === undefined ||
+            String(sourceNodeRid) === String(result.actor.nodeRid)
+          ) {
+            await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
+          } else {
+            result.reply?.close();
+          }
+          const finalization = result.finalizeDeferredJoin?.();
+          if (finalization !== undefined) {
+            await (this.turn === undefined
+              ? finalization
+              : this.turn.yieldFrameworkPromise(finalization));
+          }
         }
       });
     } catch (error) {
@@ -516,11 +517,17 @@ function createDeferredJoinDeadline(timeoutMs: number): {
 } {
   const controller = new AbortController();
   const atMs = performance.now() + timeoutMs;
-  const timer = setTimeout(() => controller.abort(createInternalFrameworkException(
-    ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-    'Deferred Actor join exceeded its absolute deadline.',
-    true
-  )), timeoutMs);
+  const timer = setTimeout(
+    () =>
+      controller.abort(
+        createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+          'Deferred Actor join exceeded its absolute deadline.',
+          true
+        )
+      ),
+    timeoutMs
+  );
   return {
     atMs,
     signal: controller.signal,
@@ -539,11 +546,10 @@ async function notifyJoinCompletion(
   _messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer> | undefined
 ): Promise<void> {
   // The completion preserves the encoded reply without exposing serializer selection.
-  const reply = result.reply === undefined
-    ? undefined
-    : ZLinkMessage.fromEncoded(
-      ZLinkEncodedPayload.from(result.reply.data())
-    );
+  const reply =
+    result.reply === undefined
+      ? undefined
+      : ZLinkMessage.fromEncoded(ZLinkEncodedPayload.from(result.reply.data()));
   result.reply?.close();
   // `reply`는 계약상 선택 항목이라 없을 때는 key 자체를 만들지 않는다.
   const replyField = reply === undefined ? {} : { reply };
@@ -569,17 +575,19 @@ async function notifyJoinFailure(
   coordinator?: ZLinkActorJoinCoordinator
 ): Promise<void> {
   console.error(`actor join failure actor=${actor.context.actorId}`, error);
-  const frameworkError = error instanceof ZLinkFrameworkException
-    ? error
-    : createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestFailed,
-        'Deferred actor join failed.',
-        false,
-        error
-      );
+  const frameworkError =
+    error instanceof ZLinkFrameworkException
+      ? error
+      : createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RequestFailed,
+          'Deferred actor join failed.',
+          false,
+          error
+        );
   //  The completion carries only an error kind, so trace the cause on the
   //  message flow under the same flow id as the Join that produced it.
   const tracePoint = coordinator?.messageFlow?.()?.begin(ZLinkMessageFlowOutcome.Error);
+  const errorDetails = tracePoint === undefined ? undefined : dispatchErrorDetails(error);
   tracePoint?.trace({
     outcome: ZLinkMessageFlowOutcome.Error,
     surface: ZLinkDispatchErrorSurface.SpotActor,
@@ -588,8 +596,8 @@ async function notifyJoinFailure(
     actorId: actor.context.actorId,
     errorReason: ZLinkDispatchErrorReason.HandlerException,
     errorAction: ZLinkDispatchErrorAction.ReplyError,
-    errorType: String(frameworkError.kind),
-    errorMessage: String(error)
+    errorType: errorDetails?.errorType,
+    errorMessage: errorDetails?.errorMessage
   });
   await actor.onJoinCompleted?.({
     status: 'failed',

package/src/runtime/actors/actor-creation.ts

@@ -1,15 +1,16 @@
-import { ZLinkFrameworkInternalErrorKind, createInternalFrameworkException } from '../framework-errors-internal';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import type {
   RoutingId,
   Type,
   ZLinkActor,
   ZLinkActorCreateResponse,
-  ZLinkActorFactory,
+  ZLinkActorFactory
 } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import {
-  ZLinkMessage
-} from '../../contracts';
+import { ZLinkMessage } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import { ZLinkConfigurationException } from '../configuration';
 import { DefaultZLinkActorContext } from './actor-context';
@@ -54,14 +55,7 @@ export class ZLinkActorCreationCoordinator {
           this.options.actorDestroyedCleanup?.(actorId);
           state.clearAfterDestroy();
         },
-        () => this.createActorAfterClaim(
-          actorId,
-          actorType,
-          state,
-          createRequest,
-          true,
-          signal
-        )
+        () => this.createActorAfterClaim(actorId, actorType, state, createRequest, true, signal)
       );
       if (activation.activated !== undefined) {
         if (activation.activated.status !== 'created') {
@@ -102,18 +96,22 @@ export class ZLinkActorCreationCoordinator {
     restore: ((actor: ZLinkActor) => Promise<void>) | undefined
   ): Promise<ZLinkActorCreationAttemptResult> {
     void actorId;
-    const context = state.ensureContext(() => new DefaultZLinkActorContext(
-      state,
-      this.options.joinCoordinator,
-      this.options.boundSessionFactory,
-      this.options.messageSerializers,
-      this.options.actorMeshNameProvider
-    ));
+    const context = state.ensureContext(
+      () =>
+        new DefaultZLinkActorContext(
+          state,
+          this.options.joinCoordinator,
+          this.options.boundSessionFactory,
+          this.options.messageSerializers,
+          this.options.actorMeshNameProvider
+        )
+    );
     const actor = await (await this.createFactory(actorType)).create(context);
     attachTransferredActorContext(actor, context);
     await restore?.(actor);
     state.bindActor(actor, context);
-    const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+    const nativeActorNode =
+      this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
     if (nativeActorNode !== undefined) {
       state.ensureNativeActorRef(nativeActorNode);
     }
@@ -129,14 +127,18 @@ export class ZLinkActorCreationCoordinator {
     signal?: AbortSignal
   ): Promise<ZLinkActorCreationAttemptResult> {
     const factory = await this.createFactory(actorType);
-    const context = state.ensureContext(() => new DefaultZLinkActorContext(
-      state,
-      this.options.joinCoordinator,
-      this.options.boundSessionFactory,
-      this.options.messageSerializers,
-      this.options.actorMeshNameProvider
-    ));
-    const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+    const context = state.ensureContext(
+      () =>
+        new DefaultZLinkActorContext(
+          state,
+          this.options.joinCoordinator,
+          this.options.boundSessionFactory,
+          this.options.messageSerializers,
+          this.options.actorMeshNameProvider
+        )
+    );
+    const nativeActorNode =
+      this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
     let actor: ZLinkActor;
     try {
       actor = await factory.create(context, signal);
@@ -154,9 +156,7 @@ export class ZLinkActorCreationCoordinator {
       }
       meshName = state.meshName ?? '';
       if (meshName.length === 0 && state.nativeActorRef === undefined) {
-        throw new ZLinkConfigurationException(
-          `Actor '${actorId}' has no RouteMesh identity.`
-        );
+        throw new ZLinkConfigurationException(`Actor '${actorId}' has no RouteMesh identity.`);
       }
       if (nativeActorNode !== undefined) {
         const actorRef = state.ensureNativeActorRef(nativeActorNode, createRequest.nativeRequest);
@@ -171,14 +171,15 @@ export class ZLinkActorCreationCoordinator {
 
     let response: ZLinkActorCreateResponse;
     try {
-      response = nodeRid === undefined
-        ? { accepted: true }
-        : await this.options.actorCreatedNotifier?.(
-          nodeRid,
-          actor,
-          createRequest.callbackRequest,
-          signal
-        ) ?? { accepted: true };
+      response =
+        nodeRid === undefined
+          ? { accepted: true }
+          : ((await this.options.actorCreatedNotifier?.(
+              nodeRid,
+              actor,
+              createRequest.callbackRequest,
+              signal
+            )) ?? { accepted: true });
     } catch (error) {
       await this.discardStagingActor(state, nativeActorNode);
       return { status: 'failed', error };
@@ -233,10 +234,12 @@ export class ZLinkActorCreationCoordinator {
   }
 
   private resolveLocationNodeRid(): RoutingId {
-    const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
-    const nodeRid = nativeActorNode === undefined
-      ? this.options.actorCreatedNodeRidProvider?.()
-      : toFrameworkRoutingId(nativeActorNode.status().routingId as never);
+    const nativeActorNode =
+      this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+    const nodeRid =
+      nativeActorNode === undefined
+        ? this.options.actorCreatedNodeRidProvider?.()
+        : toFrameworkRoutingId(nativeActorNode.status().routingId as never);
     if (nodeRid === undefined) {
       throw new ZLinkConfigurationException('Location actor claim requires a node routing id.');
     }

package/src/runtime/actors/actor-execution-context.ts

@@ -27,10 +27,12 @@ export async function runZLinkActorExecution<T>(
   });
 }
 
-export function currentZLinkActorExecution(): Readonly<{
-  actorId: string;
-  spotId?: unknown;
-}> | undefined {
+export function currentZLinkActorExecution():
+  | Readonly<{
+      actorId: string;
+      spotId?: unknown;
+    }>
+  | undefined {
   const context = actorExecutionStorage.getStore();
   return context?.active === true
     ? { actorId: context.actorId, spotId: context.spotId }