@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/streams/actor-session-binding-runtime-owner.ts

@@ -1,14 +1,8 @@
 import type { ActorRef } from '../../contracts';
-import type {
-  ServiceSessionBindingAdmissionClaim,
-  ServiceSessionBindingAdmissionResult
-} from '../foundation/service-session-binding-ingress-port';
 import type {
   ZLinkActorSessionAuthorityFence,
-  ZLinkActorSessionAcceptedProducerProof,
   ZLinkActorSessionRelocationClaim,
   ZLinkActorSessionRelocationSnapshot,
-  ZLinkActorSessionRetainedOutbound,
   ZLinkActorSessionRouteFence
 } from './actor-session-binding-registry';
 
@@ -23,23 +17,11 @@ export interface ZLinkActorSessionBindingRuntimeOwner {
     actorId: string,
     sealId: string
   ): Promise<ZLinkActorSessionRelocationSnapshot | undefined>;
-  retainRelocationOutbound(
-    actorId: string,
-    operation: ZLinkActorSessionRetainedOutbound,
-    sealId?: string
-  ): Promise<ServiceSessionBindingAdmissionResult>;
-  admitRelocationOutbound(
-    claim: ServiceSessionBindingAdmissionClaim,
-    operation: ZLinkActorSessionRetainedOutbound
-  ): Promise<ServiceSessionBindingAdmissionResult>;
-  discardRelocationOutbound(actorId: string, sealId: string, error: unknown): Promise<void>;
   applyRelocation(
     actorId: string,
     sealId: string,
     applyFingerprint: string,
-    action: 'commit' | 'abort',
-    commitOwnerTransition: () => Promise<void>,
-    acceptedProducerProof?: ZLinkActorSessionAcceptedProducerProof
+    commitOwnerTransition: () => Promise<void>
   ): Promise<void>;
   observeRelocationTerminal(
     actorId: string,

package/src/runtime/streams/bound-actor-relay-sender.ts

@@ -1,25 +1,33 @@
 import type { ZLinkMessage, ZLinkMessageSerializer, ZLinkSessionActor } from '../../contracts';
-import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
-import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
 import {
-  encodeStreamHeader,
-  messageToBytes,
-  type ZLinkStreamFrameHeader,
-  ZLinkStreamMessageKind
-} from './protocol';
+  ZLinkDispatchErrorSurface,
+  ZLinkDispatchMessageKind,
+  ZLinkRuntimeMessageFlowOutcome
+} from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import { throwIfAborted } from '../abort';
-import { captureZLinkExecutionTurn } from '../execution';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import { flowIfEnabled } from '../diagnostics';
+import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
+import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import {
   ZLinkActorSessionBindingRegistry,
   ZLinkActorSessionBindingTermination
 } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { ZLinkManagedStream } from './managed-stream';
+import {
+  encodeStreamHeader,
+  messageToBytes,
+  ZLinkStreamMessageKind,
+  type ZLinkStreamFrameHeader
+} from './protocol';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
 import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+export const DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS = 2000;
 
 export interface ZLinkBoundActorRelaySenderOptions {
+  readonly dispatchErrors?: ZLinkDispatchErrorReporter;
   readonly actorBindTimeoutMs?: number;
   readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
   readonly relay?: (
@@ -65,36 +73,47 @@ export class ZLinkBoundActorRelaySender {
           await admission.complete();
         }
       };
-      if (
-        (await this.routes.isSealed(actor.actorId)) &&
-        captureZLinkExecutionTurn() !== undefined
-      ) {
-        void operation().catch(() => undefined);
-        return { status: ZLinkSubmitStatus.Submitted };
-      }
       return await operation();
     }
-    if ((await this.routes.isSealed(actor.actorId)) && captureZLinkExecutionTurn() !== undefined) {
-      //  Spec 32:62 — a Send completes once the source outbound queue
-      //  accepts it; spec 05 — infrastructure send progress must not depend
-      //  on the application turn. When the CALLER IS an application turn
-      //  (a lifecycle callback pushing to a bound actor), awaiting the seal
-      //  release here deadlocks: the relocation seal waits for that very
-      //  callback to finish (onJoinedActor -> push -> seal ->
-      //  onJoinedActor). Accept the frame now and deliver it after the
-      //  seal releases, in per-actor order through the lifecycle lane; the
-      //  bounded seal wait converts a stuck seal into a typed failure.
-      //  Non-turn callers (stream ingress relays) keep the waiting
-      //  semantics so a held frame across a failed rebind still
-      //  terminalizes to the caller.
-      void this.routes
-        .runAcceptedFrameWhenReady(
-          actor.actorId,
-          actor.bindingToken,
-          () => this.relayAcceptedFrame(actor, payload, signal),
-          signal
-        )
-        .catch(() => undefined);
+    throwIfAborted(signal);
+    const held = await this.routes.acceptOneWay(actor.actorId, actor.bindingToken, () => {
+      let heldMessage: Message | undefined = encodeFrameworkPayloadMessage(
+        payload,
+        this.options.messageSerializers
+      );
+      return {
+        deliver: async () => {
+          try {
+            const result = await this.routes.runAcceptedFrameWhenReady(
+              actor.actorId,
+              actor.bindingToken,
+              () =>
+                this.relayAcceptedFrame(actor, payload, undefined, header, undefined, heldMessage)
+            );
+            if (result.status !== ZLinkSubmitStatus.Submitted) {
+              this.traceHeldDrop(
+                header,
+                result.status === ZLinkSubmitStatus.Backpressured ||
+                  result.status === ZLinkSubmitStatus.TimedOut
+                  ? 'backpressure'
+                  : result.status === ZLinkSubmitStatus.Shutdown
+                    ? 'shutdown'
+                    : 'stale_target'
+              );
+            }
+          } finally {
+            heldMessage?.close();
+            heldMessage = undefined;
+          }
+        },
+        drop: (reason, error) => {
+          heldMessage?.close();
+          heldMessage = undefined;
+          this.traceHeldDrop(header, reason, error);
+        }
+      };
+    });
+    if (held) {
       return { status: ZLinkSubmitStatus.Submitted };
     }
     return this.routes.runAcceptedFrameWhenReady(
@@ -105,12 +124,36 @@ export class ZLinkBoundActorRelaySender {
     );
   }
 
+  private traceHeldDrop(
+    header: ZLinkStreamFrameHeader,
+    reason: 'backpressure' | 'target_closed' | 'stale_target' | 'shutdown',
+    error?: unknown
+  ): void {
+    flowIfEnabled(
+      this.options.dispatchErrors?.flow,
+      ZLinkRuntimeMessageFlowOutcome.Dropped,
+      undefined,
+      header.flowId
+    )?.trace({
+      outcome: ZLinkRuntimeMessageFlowOutcome.Dropped,
+      surface: ZLinkDispatchErrorSurface.StreamSession,
+      messageKind: ZLinkDispatchMessageKind.Send,
+      packetName: header.name,
+      flowId: header.flowId,
+      flowOrigin: header.flowOrigin,
+      correlationId: header.correlationId,
+      errorReason: reason,
+      ...(error instanceof Error ? { errorType: error.name, errorMessage: error.message } : {})
+    });
+  }
+
   private async relayAcceptedFrame(
     actor: DefaultZLinkSessionActor,
     payload: ZLinkMessage,
     signal?: AbortSignal,
     header?: ZLinkStreamFrameHeader,
-    requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined }
+    requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined },
+    acceptedPayload?: Message
   ): Promise<ZLinkSubmitResult> {
     const activeHeader = header ?? (await this.currentHeader(actor));
     const started = await this.lifecycle.run(actor.actorId, async () => {
@@ -119,7 +162,8 @@ export class ZLinkBoundActorRelaySender {
         payload,
         signal,
         activeHeader,
-        requestAdmission
+        requestAdmission,
+        acceptedPayload
       );
       if (
         activeHeader.kind === ZLinkStreamMessageKind.Request &&
@@ -165,13 +209,15 @@ export class ZLinkBoundActorRelaySender {
     payload: ZLinkMessage,
     signal: AbortSignal | undefined,
     currentHeader?: ZLinkStreamFrameHeader,
-    requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined }
+    requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined },
+    acceptedPayload?: Message
   ): Promise<ZLinkSubmitResult> {
     const header = currentHeader ?? (await this.currentHeader(actor));
     const held = requestAdmission?.beginSubmission(signal);
     if (held !== undefined) await held;
     throwIfAborted(signal);
-    const payloadMessage = encodeFrameworkPayloadMessage(payload, this.options.messageSerializers);
+    const payloadMessage =
+      acceptedPayload ?? encodeFrameworkPayloadMessage(payload, this.options.messageSerializers);
     try {
       if (this.options.relay !== undefined) {
         const handled = await this.options.relay(actor, header, payloadMessage, signal);
@@ -198,7 +244,7 @@ export class ZLinkBoundActorRelaySender {
         framePayloadMessage.close();
       }
     } finally {
-      payloadMessage.close();
+      if (acceptedPayload === undefined) payloadMessage.close();
     }
   }
 
@@ -224,7 +270,7 @@ export class ZLinkBoundActorRelaySender {
     ) {
       await detached.context.stream.unbindActor(
         actor.actorId,
-        this.options.actorBindTimeoutMs ?? 2000,
+        this.options.actorBindTimeoutMs ?? DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS,
         signal
       );
     }
@@ -233,7 +279,7 @@ export class ZLinkBoundActorRelaySender {
 
   async notifyPhysicalDisconnect(context: DefaultZLinkSessionContext): Promise<void> {
     const snapshot = [...context.boundActors];
-    const timeoutMs = this.options.actorBindTimeoutMs ?? 2000;
+    const timeoutMs = this.options.actorBindTimeoutMs ?? DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS;
     await Promise.allSettled(
       snapshot.map(async (actor) => {
         const detached = await this.lifecycle.run(actor.actorId, async () => {

package/src/runtime/streams/bound-session-service.ts

@@ -7,11 +7,7 @@ import type { ActorRef } from '../../contracts';
 import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
 import { throwIfAborted } from '../abort';
-import type {
-  ZLinkBackendActorRef,
-  ZLinkBackendActorSessionSendFence,
-  ZLinkBackendActorSessionNode
-} from '../backend/contracts';
+import type { ZLinkBackendActorRef, ZLinkBackendActorSessionNode } from '../backend/contracts';
 import {
   encodeStreamHeader,
   resolvePacketName,
@@ -27,6 +23,8 @@ import type { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './ses
 import { boundSessionErrorPayload } from './bound-session-response-target';
 import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
 import { ZLinkManagedStream } from './managed-stream';
+import type { ZLinkSessionBindingIdentity } from './stream-binding-runtime-ports';
+import { REMOTE_BOUND_SESSION_BIND_PACKET } from '../spots/spot-remote-codec';
 
 const ZLINK_SEND_DONT_WAIT = 1;
 
@@ -305,12 +303,30 @@ export class ZLinkBoundSessionService {
     }
   }
 
+  /**
+   * Closes the physical Session of one exact binding after its relocation
+   * failed (Session–Actor binding §8.1). A newer binding of the same Actor is
+   * not selected.
+   */
+  async closeSessionBinding(
+    actorId: string,
+    expected: ZLinkSessionBindingIdentity,
+    signal?: AbortSignal
+  ): Promise<void> {
+    const route = await this.routes.routeForSessionBinding(
+      actorId,
+      expected.sessionRid,
+      expected.bindingGeneration
+    );
+    await route?.context.close(signal);
+  }
+
   async relayRemoteBoundSessionBind(stream: ZLinkManagedStream, actorRef: ActorRef): Promise<void> {
     const encodedBindHeader = encodeStreamHeader({
       kind: ZLinkStreamMessageKind.Send,
       codec: ZLinkStreamCodec.Raw,
       flags: ZLinkStreamHeaderFlags.None,
-      name: 'zlink.framework.actor.bound_session.bind',
+      name: REMOTE_BOUND_SESSION_BIND_PACKET,
       metadata: new Map()
     });
     //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
@@ -439,8 +455,7 @@ export class ZLinkBoundSessionService {
       backendActorRef,
       requireBoundSessionGeneration(actorRef),
       [frame],
-      ZLINK_SEND_DONT_WAIT,
-      boundSessionSendFence(node, backendActorRef, actorRef)
+      ZLINK_SEND_DONT_WAIT
     );
   }
 
@@ -479,32 +494,3 @@ function toBoundSessionSendActorRef(actor: ActorRef): ZLinkBackendActorRef {
     generation: actor.objectGeneration
   };
 }
-
-function boundSessionSendFence(
-  node: ZLinkBackendActorSessionNode,
-  backendActor: ZLinkBackendActorRef,
-  actor: ActorRef
-): ZLinkBackendActorSessionSendFence | undefined {
-  const internal = actor as ActorRef & {
-    readonly ownershipGeneration?: bigint;
-    readonly ownerLeaseGeneration?: bigint;
-    readonly ownerNodeGeneration?: bigint;
-  };
-  const ownerNodeGeneration =
-    internal.ownerNodeGeneration ?? node.actorNodeGeneration?.(backendActor);
-  if (
-    internal.ownershipGeneration === undefined ||
-    internal.ownershipGeneration <= 0n ||
-    internal.ownerLeaseGeneration === undefined ||
-    internal.ownerLeaseGeneration <= 0n ||
-    ownerNodeGeneration === undefined ||
-    ownerNodeGeneration <= 0n
-  ) {
-    return undefined;
-  }
-  return Object.freeze({
-    targetNodeGeneration: ownerNodeGeneration,
-    authorityOwnerGeneration: internal.ownershipGeneration,
-    ownerLeaseGeneration: internal.ownerLeaseGeneration
-  });
-}