@zlink-systems/framework 0.26.0 → 0.27.0

package/src/runtime/streams/protocol.ts

@@ -1,90 +1,52 @@
-import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkFlowOrigin } from '../../contracts';
-import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import {
+  ZlinkStreamCloseReasonCode as ZLinkStreamCloseReasonCode,
+  ZlinkStreamCodec as ZLinkStreamCodec,
+  ZlinkStreamHeaderFlags as ZLinkStreamHeaderFlags,
+  ZlinkStreamMessageKind as ZLinkStreamMessageKind,
+  ZlinkStreamControlPacket,
   decodeStreamWireFrame,
   decodeStreamWireHeader,
+  defaultMaxDecompressedPayloadSize,
+  encodeStreamWireActorBoundPayload,
+  encodeStreamWireActorUnboundPayload,
   encodeStreamWireFrame,
   encodeStreamWireHeader,
+  encodeStreamWireSessionClosingPayload,
   lz4PickleUncompressed,
   lz4UnpicklePayload,
   tryDecodeStreamWireFrame,
-  utf8Encode
+  streamCodecContentType as wireCodecContentType,
+  streamCodecForContentType as wireCodecForContentType
 } from '@zlink-systems/stream-wire';
+import type { ZLinkFlowOrigin } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import { throwAlreadySubmitted } from '../messaging/submission-result';
+export {
+  ZlinkStreamMessageKind as ZLinkStreamMessageKind,
+  ZlinkStreamHeaderFlags as ZLinkStreamHeaderFlags,
+  ZlinkStreamCloseReasonCode as ZLinkStreamCloseReasonCode
+} from '@zlink-systems/stream-wire';
 
 export { utf8Decode, utf8Encode } from '@zlink-systems/stream-wire';
 
-const defaultMaxDecompressedPayloadSize = 64 * 1024;
 const actorRequestDeadlineMetadataKey = '$zlink.actor-request-deadline-unix-ms';
 //  Shared empty metadata for the dominant no-metadata frame; ReadonlyMap
 //  keeps every consumer from mutating it.
 const EMPTY_STREAM_METADATA: ReadonlyMap<string, string> = new Map();
 
-export enum ZLinkStreamCodec {
-  Raw = 0,
-  Json = 1,
-  MessagePack = 2,
-  Protobuf = 3
-}
+export { ZlinkStreamCodec as ZLinkStreamCodec } from '@zlink-systems/stream-wire';
 
 export function streamCodecContentType(codec: ZLinkStreamCodec): string {
-  switch (codec) {
-    case ZLinkStreamCodec.Json:
-      return 'application/json';
-    case ZLinkStreamCodec.MessagePack:
-      return 'application/x-msgpack';
-    case ZLinkStreamCodec.Protobuf:
-      return 'application/x-protobuf';
-    case ZLinkStreamCodec.Raw:
-      return 'application/octet-stream';
-  }
-  throw new TypeError(`Unsupported STREAM codec '${codec}'.`);
+  return wireCodecContentType(codec);
 }
 
 export function streamCodecForContentType(contentType: string): ZLinkStreamCodec {
-  switch (contentType) {
-    case 'application/json':
-      return ZLinkStreamCodec.Json;
-    case 'application/x-msgpack':
-      return ZLinkStreamCodec.MessagePack;
-    case 'application/x-protobuf':
-      return ZLinkStreamCodec.Protobuf;
-    case 'application/octet-stream':
-      return ZLinkStreamCodec.Raw;
-  }
-  throw new TypeError(`Unsupported STREAM content type '${contentType}'.`);
+  return wireCodecForContentType(contentType);
 }
 
-export enum ZLinkStreamMessageKind {
-  Send = 1,
-  Request = 2,
-  Response = 3,
-  Error = 4,
-  Control = 5
-}
-
-export enum ZLinkStreamHeaderFlags {
-  None = 0,
-  HasRequestSeq = 0x01,
-  HasMetadata = 0x02,
-  PayloadCompressed = 0x04,
-  HasCorrelationId = 0x08,
-  HasFlowId = 0x10,
-  HasActorSlot = 0x20
-}
-
-export enum ZLinkStreamCloseReasonCode {
-  ClientClose = 1,
-  IdleTimeout = 2,
-  HeartbeatTimeout = 3,
-  ServerDrain = 4,
-  ProtocolError = 5,
-  TransportError = 6
-}
-
-export const ZLINK_STREAM_HEARTBEAT_PING = '$zlink.heartbeat.ping';
-export const ZLINK_STREAM_HEARTBEAT_PONG = '$zlink.heartbeat.pong';
+export const ZLINK_STREAM_HEARTBEAT_PING = ZlinkStreamControlPacket.HeartbeatPing;
+export const ZLINK_STREAM_HEARTBEAT_PONG = ZlinkStreamControlPacket.HeartbeatPong;
 
 export interface ZLinkStreamFrameHeader {
   readonly kind: ZLinkStreamMessageKind;
@@ -142,48 +104,32 @@ export function encodeStreamControlFrame(name: string): Uint8Array {
 }
 
 export function encodeActorBoundFrame(actorSlot: number, actorId: string): Uint8Array {
-  const actorIdBytes = utf8Encode(actorId);
-  if (actorIdBytes.length < 1 || actorIdBytes.length > 0xff) {
-    throw new Error('Actor id length is invalid for a STREAM binding control packet.');
-  }
-  const payload = new Uint8Array(4 + actorIdBytes.length);
-  payload[0] = 1;
-  payload[1] = actorSlot >>> 8;
-  payload[2] = actorSlot & 0xff;
-  payload[3] = actorIdBytes.length;
-  payload.set(actorIdBytes, 4);
-  return encodeStreamFrame(controlHeader('$zlink.actor.bound'), payload);
+  return encodeStreamFrame(
+    controlHeader(ZlinkStreamControlPacket.ActorBound),
+    encodeStreamWireActorBoundPayload(actorSlot, actorId)
+  );
 }
 
 export function encodeActorUnboundFrame(actorSlot: number): Uint8Array {
-  const payload = new Uint8Array(3);
-  payload[0] = 1;
-  payload[1] = actorSlot >>> 8;
-  payload[2] = actorSlot & 0xff;
-  return encodeStreamFrame(controlHeader('$zlink.actor.unbound'), payload);
+  return encodeStreamFrame(
+    controlHeader(ZlinkStreamControlPacket.ActorUnbound),
+    encodeStreamWireActorUnboundPayload(actorSlot)
+  );
 }
 
 export function encodeSessionClosingFrame(
   diagnostic = '',
   reason = ZLinkStreamCloseReasonCode.ServerDrain
 ): Uint8Array {
-  const diagnosticBytes = utf8Encode(diagnostic);
-  if (diagnosticBytes.length > 512) throw new Error('Session-closing diagnostic is too large.');
-  const payload = new Uint8Array(4 + diagnosticBytes.length);
-  payload[0] = 1;
-  payload[1] = reason;
-  payload[2] = diagnosticBytes.length >>> 8;
-  payload[3] = diagnosticBytes.length & 0xff;
-  payload.set(diagnosticBytes, 4);
   return encodeStreamFrame(
     {
       kind: ZLinkStreamMessageKind.Control,
       codec: ZLinkStreamCodec.Raw,
       flags: ZLinkStreamHeaderFlags.None,
-      name: 'session-closing',
+      name: ZlinkStreamControlPacket.SessionClosing,
       metadata: new Map()
     },
-    payload
+    encodeStreamWireSessionClosingPayload(reason, diagnostic)
   );
 }
 

package/src/runtime/streams/session-actor-coordinator.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS } from './bound-actor-relay-sender';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
@@ -13,6 +14,7 @@ import {
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { ZLinkManagedStream } from './managed-stream';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import type { ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
 
 export interface ZLinkSessionActorCoordinatorOptions {
   readonly actorBindTimeoutMs?: number;
@@ -31,7 +33,7 @@ export interface ZLinkSessionActorCoordinatorOptions {
     actor: ActorRef,
     sessionRid: ActorRef['nodeRid'],
     signal?: AbortSignal,
-    options?: { readonly waitForAcknowledgement?: boolean }
+    options?: ZLinkSessionBindingConfirmationOptions
   ) => Promise<void>;
   readonly errorSink?: () =>
     | {
@@ -181,7 +183,13 @@ export class ZLinkSessionActorCoordinator {
         boundActorRef,
         this.actorBindingRoutingId(context),
         undefined,
-        { waitForAcknowledgement }
+        {
+          waitForAcknowledgement,
+          binding:
+            context.stream instanceof ZLinkManagedStream
+              ? context.stream.actorBinding(actorRef.actorId)
+              : undefined
+        }
       );
       const reportFailure = (error: unknown) => {
         // A fire-and-forget route update retains the already-current binding;
@@ -204,7 +212,7 @@ export class ZLinkSessionActorCoordinator {
             if (context.stream instanceof ZLinkManagedStream) {
               await context.stream.unbindActor(
                 actorRef.actorId,
-                this.options.actorBindTimeoutMs ?? 2000
+                this.options.actorBindTimeoutMs ?? DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS
               );
             }
           } catch (cleanupError) {
@@ -354,7 +362,11 @@ export class ZLinkSessionActorCoordinator {
             true
           );
         }
-        route.actor.updateRef(normalizedActorRef);
+        // A location refresh never changes the route's Session binding
+        // generation; the native bind owns it.
+        route.actor.updateRef(
+          withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined)
+        );
         if (authorityFence !== undefined) {
           await this.routes.updateAuthorityFence(normalizedActorRef.actorId, authorityFence);
         }
@@ -463,7 +475,7 @@ export class ZLinkSessionActorCoordinator {
     try {
       await context.stream.bindActor(
         actorRef,
-        this.options.actorBindTimeoutMs ?? 2000,
+        this.options.actorBindTimeoutMs ?? DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS,
         signal,
         context.actorBindingReplacedHandler,
         authorityFence

package/src/runtime/streams/session-calls.ts

@@ -1,14 +1,15 @@
-import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
 import type {
   ZLinkBoundSessionSendCall,
   ZLinkSessionReplyCall,
   ZLinkSessionSendCall
 } from '../../contracts';
-import type { ZLinkSubmitResult } from '../messaging/submission-result';
-import { requireOneWayCompletion } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
+import { ZLINK_MAX_SEND_TIMEOUT_MS } from '../../contracts/Configuration/SendTimeoutValidation';
 import { throwIfAborted } from '../abort';
 import { ZLinkConfigurationException } from '../configuration';
+import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
+import { type ZLinkSubmitResult, requireOneWayCompletion } from '../messaging/submission-result';
+
 import {
   ensureSingleSubmit,
   resolvePacketName,
@@ -135,9 +136,9 @@ export class DefaultZLinkSessionSendCall implements ZLinkSessionSendCall {
   }
 
   timeout(timeoutMs: number): this {
-    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > ZLINK_MAX_SEND_TIMEOUT_MS) {
       throw new ZLinkConfigurationException(
-        'STREAM session send timeout must be an integer from 1 through 2147483647 milliseconds.'
+        `STREAM session send timeout must be an integer from 1 through ${ZLINK_MAX_SEND_TIMEOUT_MS} milliseconds.`
       );
     }
     this.selectedTimeoutMs = timeoutMs;

package/src/runtime/streams/session-context.ts

@@ -1,11 +1,10 @@
-import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
 import type {
   ActorRef,
   RoutingId,
   Type,
-  ZLinkMessage,
   ZLinkActor,
   ZLinkBoundSession,
+  ZLinkMessage,
   ZLinkSessionActor,
   ZLinkSessionActors,
   ZLinkSessionClient,
@@ -17,18 +16,27 @@ import type {
   ZLinkSessionSendCall,
   ZLinkStream
 } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import type { ZLinkSubmitResult } from '../messaging/submission-result';
-import { requireOneWayCompletion } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
 import { throwIfAborted } from '../abort';
+import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
 import { ZLinkConfigurationException } from '../configuration';
+import {
+  guardStateLaneCompletion,
+  isStructuralGuardEnabled,
+  trackDiagnosticCompletion
+} from '../execution/state-lane';
+import type { ServiceActorRef } from '../foundation/service-stateful-registry';
+import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service-stateful-wire-codec';
+import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
+import { type ZLinkSubmitResult, requireOneWayCompletion } from '../messaging/submission-result';
+
 import {
   messageToBytes,
-  type ZLinkStreamFrameHeader,
   ZLinkStreamHeaderFlags,
   ZLinkStreamMessageKind,
+  type ZLinkStreamFrameHeader,
   type ZLinkStreamReplyMessageKind
 } from './protocol';
 import {
@@ -36,11 +44,8 @@ import {
   DefaultZLinkSessionReplyCall,
   DefaultZLinkSessionSendCall
 } from './session-calls';
-import { ZLinkSessionRequestTracker, type ZLinkPendingSessionRequest } from './session-requests';
 import { ZLinkSessionLocalActorBindings } from './session-local-actors';
-import type { ServiceActorRef } from '../foundation/service-stateful-registry';
-import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service-stateful-wire-codec';
-import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
+import { ZLinkSessionRequestTracker, type ZLinkPendingSessionRequest } from './session-requests';
 
 export interface ZLinkSessionContextStream extends ZLinkStream {
   writeRaw(payload: Message, flags?: number): boolean;
@@ -652,3 +657,42 @@ function sameRetiredSession(
     left.retiredBindingGeneration === right.retiredBindingGeneration
   );
 }
+
+if (isStructuralGuardEnabled()) {
+  const controlsGetter = Object.getOwnPropertyDescriptor(
+    DefaultZLinkSessionContext.prototype,
+    'actorSlotControls'
+  )?.get;
+  if (controlsGetter !== undefined) {
+    Object.defineProperty(DefaultZLinkSessionContext.prototype, 'actorSlotControls', {
+      configurable: true,
+      get(this: DefaultZLinkSessionContext) {
+        const controls = controlsGetter.call(this) as
+          | {
+              enqueueBound(actorSlot: number, actorId: string): Promise<void>;
+              enqueueUnbound(actorSlot: number): Promise<void>;
+            }
+          | undefined;
+        if (controls === undefined) return undefined;
+        return {
+          enqueueBound: (actorSlot: number, actorId: string) =>
+            guardStateLaneCompletion(
+              trackDiagnosticCompletion(
+                controls.enqueueBound(actorSlot, actorId),
+                `binding transport bound ${actorId}`
+              ),
+              'binding transport completion'
+            ),
+          enqueueUnbound: (actorSlot: number) =>
+            guardStateLaneCompletion(
+              trackDiagnosticCompletion(
+                controls.enqueueUnbound(actorSlot),
+                `binding transport unbound ${actorSlot}`
+              ),
+              'binding transport completion'
+            )
+        };
+      }
+    });
+  }
+}

package/src/runtime/streams/session-requests.ts

@@ -1,3 +1,4 @@
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import type { Message } from '../../contracts/Common/Message';
 import { copyMessage } from './stream-message-utils';
 
@@ -102,7 +103,7 @@ export class ZLinkSessionRequestTracker {
 
   private next(): bigint {
     do {
-      this.nextRequestSeq = (this.nextRequestSeq + 1n) & 0xffffffffffffffffn;
+      this.nextRequestSeq = (this.nextRequestSeq + 1n) & UINT64_MAX;
     } while (this.nextRequestSeq === 0n);
     return this.nextRequestSeq;
   }

package/src/runtime/streams/stream-binding-runtime-ports.ts

@@ -3,6 +3,7 @@ import type { ZLinkBackendActorSessionNode } from '../backend';
 import type { ZLinkSubmitResult } from '../messaging/submission-result';
 import type { DefaultZLinkSessionActor } from './session-context';
 import type { ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
+import type { ServiceStreamSessionBinding } from '../foundation/service-runtime-contracts';
 
 export interface ZLinkStreamActorLookupPort {
   find(actorId: string): Promise<DefaultZLinkSessionActor | undefined>;
@@ -74,8 +75,28 @@ export interface ZLinkBoundSessionResponsePort {
   ): Promise<boolean>;
 }
 
+/**
+ * Session–Actor binding §5: the Session owner's registry snapshot travels with
+ * the bind confirmation so a same-node Actor owner installs the same identity a
+ * remote command 38 would carry.
+ */
+export interface ZLinkSessionBindingConfirmationOptions {
+  readonly waitForAcknowledgement?: boolean;
+  readonly binding?: ServiceStreamSessionBinding;
+}
+
+/** The exact Session binding identity a relocation validated (§8.1). */
+export interface ZLinkSessionBindingIdentity {
+  readonly sessionRid: string;
+  readonly bindingGeneration: bigint;
+}
+
 export interface ZLinkRemoteBoundSessionPort extends ZLinkStreamActorLifecyclePort {
-  disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+  closeSessionBinding(
+    actorId: string,
+    expected: ZLinkSessionBindingIdentity,
+    signal?: AbortSignal
+  ): Promise<void>;
   sendLocalBoundSession(
     actorId: string,
     message: unknown,

package/src/runtime/streams/stream-frame-factory.ts

@@ -1,4 +1,5 @@
 import type { ZLinkStreamCompressionCodec, ZLinkStreamCompressionOptions } from '../../contracts';
+import { defaultMaxDecompressedPayloadSize } from '@zlink-systems/stream-wire';
 import type { Message } from '../../contracts/Common/Message';
 import { ZLinkBufferMessage as ZLinkBindingMessage } from '../backend/runtime-message';
 import { currentOrCreateFlow } from '../diagnostics/flow-context';
@@ -18,8 +19,6 @@ import {
   type ZLinkStreamReplyMessageKind
 } from './protocol';
 
-const DEFAULT_MAX_DECOMPRESSED_STREAM_PAYLOAD_SIZE = 64 * 1024;
-
 export interface ZLinkStreamFramePayloadCodec {
   encode(
     payload: unknown,
@@ -245,7 +244,7 @@ function compressStreamPayload(
 export function decompressStreamPayload(
   payload: Uint8Array,
   codec: ZLinkStreamCompressionCodec | undefined,
-  maxDecompressedSize = DEFAULT_MAX_DECOMPRESSED_STREAM_PAYLOAD_SIZE
+  maxDecompressedSize = defaultMaxDecompressedPayloadSize
 ): Uint8Array {
   if (codec === undefined) {
     throw new Error('Compression codec is not configured.');