@zlink-systems/framework 0.26.0 → 0.28.0

package/src/runtime/locations/spot-location-claims.ts

@@ -169,7 +169,59 @@ export class ZLinkSpotLocationClaims {
     tracked.storeVersion = result.storeVersion.value;
     onCommitted();
     return {
-      release: async () => undefined
+      release: () => this.release(meshName, spotId),
+      reincarnate: async (initialize) => {
+        const reincarnated = await store.compareExchangeAuthority(key, result.storeVersion, {
+          kind: 'put',
+          generationTransition: 'reincarnate',
+          payload: replaceServiceRelocationAuthorityApplicationPayload(
+            result.payload,
+            encodeServiceInstanceAuthorityPayload({ ...decoded, state: 'coldActivating' })
+          )
+        });
+        if (reincarnated.kind !== 'stored') {
+          throw createInternalFrameworkException(
+            reincarnated.kind === 'generationExhausted'
+              ? ZLinkFrameworkInternalErrorKind.InvalidOperation
+              : ZLinkFrameworkInternalErrorKind.SpotMoving,
+            `Instance Spot '${String(spotId)}' Closing authority changed before reincarnation.`
+          );
+        }
+        this.trackInstanceAuthority({
+          ...tracked,
+          objectGeneration: reincarnated.objectGeneration,
+          authorityOwnerGeneration: reincarnated.authorityOwnerGeneration,
+          storeVersion: reincarnated.storeVersion.value
+        });
+        this.invalidateSpotRoute?.(spotId);
+        try {
+          await initialize({ ...reincarnated, kind: 'snapshot', stableType: tracked.stableType });
+          const ready = await store.compareExchangeAuthority(key, reincarnated.storeVersion, {
+            kind: 'put',
+            generationTransition: 'preserve',
+            payload: replaceServiceRelocationAuthorityApplicationPayload(
+              reincarnated.payload,
+              encodeServiceInstanceAuthorityPayload({ ...decoded, state: 'ready' })
+            )
+          });
+          if (ready.kind !== 'stored') {
+            throw createInternalFrameworkException(
+              ready.kind === 'generationExhausted'
+                ? ZLinkFrameworkInternalErrorKind.InvalidOperation
+                : ZLinkFrameworkInternalErrorKind.SpotMoving,
+              `Instance Spot '${String(spotId)}' reincarnation authority changed before initialization completed.`
+            );
+          }
+          const latest = this.spots.get(canonical);
+          if (latest?.kind === 'authority' && latest.objectGeneration === ready.objectGeneration) {
+            latest.storeVersion = ready.storeVersion.value;
+          }
+          return { ...ready, kind: 'snapshot', stableType: tracked.stableType };
+        } catch (error) {
+          await this.release(meshName, spotId, reincarnated.objectGeneration);
+          throw error;
+        }
+      }
     };
   }
 
@@ -354,6 +406,11 @@ export interface ZLinkTrackedInstanceAuthority {
 
 export interface ZLinkInstanceClosingAuthority {
   release(): Promise<void>;
+  reincarnate?(
+    initialize: (
+      authority: ZLinkAuthoritySnapshot & { readonly stableType: string }
+    ) => Promise<void>
+  ): Promise<ZLinkAuthoritySnapshot & { readonly stableType: string }>;
 }
 
 interface TrackedLegacySpot {

package/src/runtime/messaging/payload-codec.ts

@@ -1,3 +1,4 @@
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
@@ -31,6 +32,8 @@ import {
   matchEveryDeclaredMessageType
 } from '../../contracts/Configuration/CodecSerializerSelection';
 
+const MAX_DECLARED_TYPE_SELECTIONS = 1024;
+
 export interface ZLinkSerializerRegistryLike {
   readonly serializers: ReadonlyMap<string, ZLinkMessageSerializer>;
 }
@@ -49,7 +52,12 @@ interface ZLinkSerializerSelectionPlan {
 }
 
 const noSerializer = Symbol('noSerializer');
-const JSON_CONTENT_TYPE = 'application/json';
+const JSON_CONTENT_TYPE = ZlinkStreamContentType.Json;
+const frameworkJsonReceiveCodec = Symbol('frameworkJsonReceiveCodec');
+const defaultReceiveCodecs: ReadonlyMap<string, typeof frameworkJsonReceiveCodec> = new Map<
+  string,
+  typeof frameworkJsonReceiveCodec
+>([[JSON_CONTENT_TYPE, frameworkJsonReceiveCodec]]);
 
 // Registration maps are created during host configuration and are immutable
 // for the runtime lifetime. Compile the candidate list and reverse content
@@ -84,9 +92,9 @@ export function encodeFrameworkPayload(
       return {
         message: rememberContentType(
           toRuntimeMessage(payload.toEncodedPayload()),
-          'application/octet-stream'
+          ZlinkStreamContentType.Raw
         ),
-        contentType: 'application/octet-stream'
+        contentType: ZlinkStreamContentType.Raw
       };
     }
     declaredType = readZLinkMessageDeclaredType(payload);
@@ -141,7 +149,7 @@ export function decodeFrameworkPayloadMessage<T>(
   message: Message,
   registry?: ZLinkSerializerRegistryLike | ReadonlyMap<string, ZLinkMessageSerializer>,
   type?: Type<T>,
-  contentType = JSON_CONTENT_TYPE,
+  contentType: string = JSON_CONTENT_TYPE,
   packetName?: string,
   contractPart: 'payload' | 'reply' = 'payload'
 ): T {
@@ -152,7 +160,7 @@ export function decodeFrameworkTypedPayloadMessage<T>(
   message: Message,
   registry?: ZLinkSerializerRegistryLike | ReadonlyMap<string, ZLinkMessageSerializer>,
   type?: Type<T>,
-  contentType = JSON_CONTENT_TYPE,
+  contentType: string = JSON_CONTENT_TYPE,
   packetName?: string,
   contractPart: 'payload' | 'reply' = 'payload'
 ): T {
@@ -167,17 +175,10 @@ function decodeFrameworkPayload<T>(
   packetName: string | undefined,
   contractPart: 'payload' | 'reply'
 ): T {
-  if (!isCanonicalCodecContentType(contentType)) {
-    throw unsupportedContentType(contentType);
-  }
-  if (contentType !== JSON_CONTENT_TYPE) {
-    const serializer = serializerMapOf(registry)?.get(contentType);
-    if (serializer === undefined) throw unsupportedContentType(contentType);
+  const codec = receiveCodecFor(contentType, registry);
+  if (codec !== frameworkJsonReceiveCodec) {
     if (message.isEmpty()) return undefined as T;
-    return serializer.deserialize(
-      encodedPayloadFromOwned(message.data()),
-      (type ?? Object) as Type<T>
-    );
+    return codec.deserialize(encodedPayloadFromOwned(message.data()), (type ?? Object) as Type<T>);
   }
 
   if (message.isEmpty()) return undefined as T;
@@ -197,7 +198,7 @@ function decodeFrameworkPayload<T>(
 export function wrapFrameworkPayloadMessage(
   message: Message,
   registry?: ZLinkSerializerRegistryLike | ReadonlyMap<string, ZLinkMessageSerializer>,
-  contentType = JSON_CONTENT_TYPE,
+  contentType: string = JSON_CONTENT_TYPE,
   packetName?: string,
   contractPart: 'payload' | 'reply' = 'payload'
 ): ZLinkMessage {
@@ -215,14 +216,10 @@ function decodeFrameworkEncodedPayload<T>(
   packetName: string | undefined,
   contractPart: 'payload' | 'reply'
 ): T {
-  if (!isCanonicalCodecContentType(contentType)) {
-    throw unsupportedContentType(contentType);
-  }
-  if (contentType !== JSON_CONTENT_TYPE) {
-    const serializer = serializerMapOf(registry)?.get(contentType);
-    if (serializer === undefined) throw unsupportedContentType(contentType);
+  const codec = receiveCodecFor(contentType, registry);
+  if (codec !== frameworkJsonReceiveCodec) {
     if (payload.isEmpty()) return undefined as T;
-    return serializer.deserialize(payload, (type ?? Object) as Type<T>);
+    return codec.deserialize(payload, (type ?? Object) as Type<T>);
   }
   if (payload.isEmpty()) return undefined as T;
   const text = payload.getString('utf8');
@@ -241,6 +238,20 @@ function decodeFrameworkEncodedPayload<T>(
   }
 }
 
+function receiveCodecFor(
+  contentType: string,
+  registry: ZLinkSerializerRegistryLike | ReadonlyMap<string, ZLinkMessageSerializer> | undefined
+): ZLinkMessageSerializer | typeof frameworkJsonReceiveCodec {
+  if (!isCanonicalCodecContentType(contentType)) {
+    throw unsupportedContentType(contentType);
+  }
+  const registeredCodec = serializerMapOf(registry)?.get(contentType);
+  if (registeredCodec !== undefined) return registeredCodec;
+  const defaultCodec = defaultReceiveCodecs.get(contentType);
+  if (defaultCodec !== undefined) return defaultCodec;
+  throw unsupportedContentType(contentType);
+}
+
 function schemaForDecode(
   type: Type<unknown> | undefined,
   packetName: string | undefined,
@@ -316,7 +327,7 @@ function serializerSelectionPlanOf(
         return cached === noSerializer ? undefined : cached;
       }
       const selected = selectSerializerFromEntries(frozenEntries, declaredType);
-      if (cachedBusinessTypeCount < 1024) {
+      if (cachedBusinessTypeCount < MAX_DECLARED_TYPE_SELECTIONS) {
         outboundByBusinessType.set(declaredType, selected ?? noSerializer);
         cachedBusinessTypeCount += 1;
       }

package/src/runtime/messaging/request-deadline.ts

@@ -0,0 +1,58 @@
+import { awaitWithAbort } from '../abort';
+import {
+  createInternalFrameworkException,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+
+export function remainingRequestTimeout(
+  operation: string,
+  deadlineMs: number | undefined
+): number | undefined {
+  if (deadlineMs === undefined) return undefined;
+  const remaining = deadlineMs - performance.now();
+  if (remaining <= 0) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+      `${operation} exceeded its deadline.`
+    );
+  }
+  return Math.max(1, Math.ceil(remaining));
+}
+
+/** Bounds caller waiting across outbound admission and reply; late completions stay observed. */
+export async function waitRequestReply<T>(
+  reply: Promise<T>,
+  operation: string,
+  deadlineMs: number | undefined,
+  signal?: AbortSignal,
+  endWait?: () => void,
+  discardLateReply?: (reply: T) => void
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let waiting = reply;
+  if (deadlineMs !== undefined) {
+    const timeout = new Promise<never>((_resolve, reject) => {
+      const remaining = remainingRequestTimeout(operation, deadlineMs);
+      timer = setTimeout(
+        () =>
+          reject(
+            createInternalFrameworkException(
+              ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+              `${operation} exceeded its deadline.`
+            )
+          ),
+        remaining
+      );
+    });
+    waiting = Promise.race([reply, timeout]);
+  }
+  try {
+    return await awaitWithAbort(waiting, signal);
+  } catch (error) {
+    endWait?.();
+    if (discardLateReply !== undefined) void reply.then(discardLateReply, () => undefined);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/runtime/messaging/submission-result.ts

@@ -1,7 +1,10 @@
 import {
   ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
+  createInternalFrameworkException,
+  requestResultToPublicErrorKind
 } from '../framework-errors-internal';
+import { ZLinkFrameworkException } from '../../contracts';
+import { RequestResult, SubmitResult } from '../backend/runtime-values';
 export enum ZLinkSubmitStatus {
   Submitted = 'submitted',
   Backpressured = 'backpressured',
@@ -15,6 +18,59 @@ export interface ZLinkSubmitResult {
   readonly status: ZLinkSubmitStatus;
 }
 
+/** Projects immediate refusal and pending admission failure from their Core phase. */
+export function submitToRequestResult(result: number, phase: 'submit' | 'completion'): number {
+  switch (result) {
+    case SubmitResult.Ok:
+      return RequestResult.Ok;
+    case SubmitResult.Backpressured:
+      return phase === 'submit' ? RequestResult.NotConnected : RequestResult.TimedOut;
+    case SubmitResult.NotConnected:
+      return RequestResult.NotConnected;
+    case SubmitResult.NotFound:
+      return phase === 'submit' ? RequestResult.NotFound : RequestResult.NotConnected;
+    case SubmitResult.NotAdmitted:
+      return RequestResult.Rejected;
+    case SubmitResult.InvalidHandle:
+    case SubmitResult.InvalidArgument:
+    case SubmitResult.ThreadViolation:
+      return RequestResult.InvalidArgument;
+    case SubmitResult.InvalidState:
+      return RequestResult.InvalidState;
+    case SubmitResult.NotSupported:
+      return RequestResult.NotSupported;
+    case SubmitResult.Terminated:
+      return RequestResult.Terminated;
+    default:
+      return RequestResult.InternalError;
+  }
+}
+
+export function classifySubmitResult(
+  result: number,
+  operation: string,
+  phase: 'submit' | 'completion' = 'submit'
+): ZLinkSubmitResult {
+  const terminal = submitToRequestResult(result, phase);
+  switch (terminal) {
+    case RequestResult.Ok:
+      return { status: ZLinkSubmitStatus.Submitted };
+    case RequestResult.TimedOut:
+      return { status: ZLinkSubmitStatus.TimedOut };
+    case RequestResult.NotFound:
+      return { status: ZLinkSubmitStatus.TargetNotFound };
+    case RequestResult.NotConnected:
+      return { status: ZLinkSubmitStatus.RouteNotConnected };
+    case RequestResult.Terminated:
+      return { status: ZLinkSubmitStatus.Shutdown };
+    default:
+      throw new ZLinkFrameworkException(
+        requestResultToPublicErrorKind(terminal),
+        `${operation} failed with submit result ${result}.`
+      );
+  }
+}
+
 export function requireOneWayCompletion(
   result: ZLinkSubmitResult,
   operation: string,
@@ -24,12 +80,17 @@ export function requireOneWayCompletion(
     case ZLinkSubmitStatus.Submitted:
       return;
     case ZLinkSubmitStatus.TimedOut:
-    case ZLinkSubmitStatus.Backpressured:
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
         `${operation} did not obtain admission before its deadline.`,
         true
       );
+    case ZLinkSubmitStatus.Backpressured:
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+        `${operation} has no admission wait token.`,
+        true
+      );
     case ZLinkSubmitStatus.TargetNotFound:
       throw createInternalFrameworkException(notFoundKind, `${operation} target was not found.`);
     case ZLinkSubmitStatus.RouteNotConnected:
@@ -50,6 +111,15 @@ export function requirePublishCompletion(result: ZLinkSubmitResult, operation: s
   requireOneWayCompletion(result, operation);
 }
 
+export function requireClassicFanoutCompletion(result: ZLinkSubmitResult, operation: string): void {
+  requireOneWayCompletion(
+    result.status === ZLinkSubmitStatus.Backpressured
+      ? { status: ZLinkSubmitStatus.TimedOut }
+      : result,
+    operation
+  );
+}
+
 export function throwAlreadySubmitted(operation: string): never {
   throw createInternalFrameworkException(
     ZLinkFrameworkInternalErrorKind.AlreadySubmitted,

package/src/runtime/protocol/service_wire_codec.generated.ts

@@ -4257,7 +4257,7 @@ function readChannelEntry(reader: Reader, context: ServiceWireDecoderContext, en
 
 
   value["weight"] = readU32(reader, context, value, flags);
-  if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 100n) fail("weight constraint");
+  if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 10000n) fail("weight constraint");
 
 
 
@@ -4273,7 +4273,7 @@ function writeChannelEntry(input: ChannelEntry, writer: Writer, context: Service
 
   writeText8(value["channelName"], writer, context, value, flags);
   if (value["weight"] === undefined) fail("weight required");
-  if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 100n) fail("weight constraint");
+  if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 10000n) fail("weight constraint");
 
   writeU32(value["weight"], writer, context, value, flags);
 }
@@ -4451,7 +4451,7 @@ function readDescriptorExtension(reader: Reader, context: ServiceWireDecoderCont
             item.done("objectRole"); break;
       case 8:
             if (value["placementWeight"] !== undefined) fail("descriptor-extension duplicate"); value["placementWeight"] = readU32(item, context, value, flags);
-            if (numeric(value["placementWeight"]) < 0n || numeric(value["placementWeight"]) > 100n) fail("placementWeight constraint");
+            if (numeric(value["placementWeight"]) < 0n || numeric(value["placementWeight"]) > 10000n) fail("placementWeight constraint");
 
             item.done("placementWeight"); break;
       case 9:
@@ -4526,7 +4526,7 @@ function writeDescriptorExtension(input: DescriptorExtension, writer: Writer, co
     const item = new Writer(); writeObjectRole(value["objectRole"], item, context, value, flags); const itemBytes = item.result(); writeU8(7, body, context, value, flags); writeU32(itemBytes.length, body, context, value, flags); body.put(itemBytes);
   }
   if (value["placementWeight"] !== undefined) {
-    if (numeric(value["placementWeight"]) < 0n || numeric(value["placementWeight"]) > 100n) fail("placementWeight constraint");
+    if (numeric(value["placementWeight"]) < 0n || numeric(value["placementWeight"]) > 10000n) fail("placementWeight constraint");
 
     const item = new Writer(); writeU32(value["placementWeight"], item, context, value, flags); const itemBytes = item.result(); writeU8(8, body, context, value, flags); writeU32(itemBytes.length, body, context, value, flags); body.put(itemBytes);
   }
@@ -4660,7 +4660,7 @@ function readClientServerAdmission(reader: Reader, context: ServiceWireDecoderCo
 
 
     value["weight"] = readU32(body, context, value, flags);
-    if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 100n) fail("weight constraint");
+    if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 10000n) fail("weight constraint");
 
     value["runtimeState"] = readRuntimeState(body, context, value, flags);
 
@@ -4726,7 +4726,7 @@ function writeClientServerAdmission(input: ClientServerAdmission, writer: Writer
 
     writeNonzeroU64(numeric(value["descriptorRevision"]), body, context, value, flags);
     if (value["weight"] === undefined) fail("weight required");
-    if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 100n) fail("weight constraint");
+    if (numeric(value["weight"]) < 0n || numeric(value["weight"]) > 10000n) fail("weight constraint");
 
     writeU32(value["weight"], body, context, value, flags);
     if (value["runtimeState"] === undefined) fail("runtimeState required");
@@ -6376,7 +6376,7 @@ function writeFrozenRecord(input: FrozenRecord, writer: Writer, context: Service
 export function decodeFrozenRecord(bytes: Uint8Array, context: ServiceWireDecoderContext): FrozenRecord { const reader = new Reader(bytes); const value = readFrozenRecord(reader, context, {}, 0); reader.done("frozen-record"); return value; }
 export function encodeFrozenRecord(value: FrozenRecord, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeFrozenRecord(value, writer, context, {}, 0); return writer.result(); }
 
-export type InstanceRouteV1 = { readonly routeKind: "ready"; readonly targetNodeRid: Rid; readonly targetNodeGeneration: NonzeroU64; readonly targetSpotId: Text8; readonly authority: AuthorityGenerationFence } | { readonly routeKind: "coldActivation"; readonly targetNodeRid: Rid; readonly targetNodeGeneration: NonzeroU64; readonly targetSpotId: Text8; readonly targetMeshName: Text8; readonly stableType: Text8; readonly targetDescriptorVersion: Text8; readonly deadlineUnixMs: NonzeroU64 };
+export type InstanceRouteV1 = { readonly routeKind: "ready"; readonly targetNodeRid: Rid; readonly targetNodeGeneration: NonzeroU64; readonly targetSpotId: Text8; readonly authority: AuthorityGenerationFence; readonly instanceIntent: Bool8 } | { readonly routeKind: "coldActivation"; readonly targetNodeRid: Rid; readonly targetNodeGeneration: NonzeroU64; readonly targetSpotId: Text8; readonly targetMeshName: Text8; readonly stableType: Text8; readonly targetDescriptorVersion: Text8; readonly deadlineUnixMs: NonzeroU64 };
 
 function readInstanceRouteV1(reader: Reader, context: ServiceWireDecoderContext, enclosing: any, flags: number): InstanceRouteV1 {
   void context; void enclosing; void flags;
@@ -6396,6 +6396,9 @@ function readInstanceRouteV1(reader: Reader, context: ServiceWireDecoderContext,
     value["authority"] = readAuthorityGenerationFence(body, context, value, flags);
 
 
+    value["instanceIntent"] = readBool8(body, context, value, flags);
+
+
   } else if (same(value["routeKind"], "coldActivation")) {
     value["targetNodeRid"] = readRid(body, context, value, flags);
 
@@ -6441,6 +6444,9 @@ function* readIncrementalInstanceRouteV1(reader: IncrementalInput, context: Serv
     value["authority"] = yield* readIncrementalAuthorityGenerationFence(body, context, value, flags);
 
 
+    value["instanceIntent"] = yield* readIncrementalBool8(body, context, value, flags);
+
+
   } else if (same(value["routeKind"], "coldActivation")) {
     value["targetNodeRid"] = yield* readIncrementalRid(body, context, value, flags);
 
@@ -6491,8 +6497,12 @@ function writeInstanceRouteV1(input: InstanceRouteV1, writer: Writer, context: S
 
 
     writeAuthorityGenerationFence(value["authority"], body, context, value, flags);
+    if (value["instanceIntent"] === undefined) fail("instanceIntent required");
+
+
+    writeBool8(value["instanceIntent"], body, context, value, flags);
   } else if (same(value["routeKind"], "coldActivation")) {
-    if (value["authority"] !== undefined) fail("instance-route-v1 discriminator agreement");
+    if (value["authority"] !== undefined || value["instanceIntent"] !== undefined) fail("instance-route-v1 discriminator agreement");
     if (value["targetNodeRid"] === undefined) fail("targetNodeRid required");
 
 

package/src/runtime/protocol/service_wire_pilot_codec.generated.ts

@@ -1,4 +1,4 @@
-// <auto-generated> DO NOT EDIT. schema-sha256: 6d5af5cdfeff1a66c4249f2cc3b93236fa0ba07d6458d7633ef3f45e77a27d4e
+// <auto-generated> DO NOT EDIT. schema-sha256: 77748ba8f585cb70ad337fa3203b5f9b9aa7a89e7f95f7fdc20159c30987be0f
 export interface ServiceWireRouteFence { readonly id: string; readonly generation: bigint; readonly targetNodeRid: Uint8Array; readonly targetNodeGeneration: bigint; readonly expectedAuthorityOwnerGeneration: bigint; readonly expectedOwnerLeaseGeneration: bigint; }
 	export interface ApplicationPayloadEnvelopeV1 { readonly packetName: string; readonly contentType: string; readonly payload: Uint8Array; }
 	export interface ActorJoin28 { readonly correlation: bigint; readonly actor: ServiceWireRouteFence; readonly entry: boolean; readonly targetSpot: ServiceWireRouteFence; readonly payload?: ApplicationPayloadEnvelopeV1; }

package/src/runtime/spots/formal-remote-actor-transfer-registry.ts

@@ -1,5 +1,5 @@
 import type { RoutingId, ZLinkActor } from '../../contracts';
-import type { ZLinkDeferredJoinCompletion } from '../actors';
+import type { ZLinkDeferredJoinCompletion, ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import { ZLinkStateLane } from '../execution/state-lane';
 
@@ -9,6 +9,8 @@ export interface ZLinkFormalRemoteActorTransfer {
   readonly transferId: string;
   readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
   readonly deferredJoinCompletion?: ZLinkDeferredJoinCompletion;
+  /** The Session seal this relocation carries until it publishes command 44. */
+  readonly sealedSession?: ZLinkRemoteBoundSessionTarget;
   readonly targetLifecycleCompleted: Promise<void>;
   readonly sourceLeaveSubmitted: Promise<boolean>;
 }
@@ -44,6 +46,7 @@ export class ZLinkFormalRemoteActorTransferRegistry {
     readonly transferId: string;
     readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
     readonly deferredJoinCompletion?: ZLinkDeferredJoinCompletion;
+    readonly sealedSession?: ZLinkRemoteBoundSessionTarget;
   }): ZLinkFormalRemoteActorTransfer {
     const existingByActor = this.transfers.get(input.actor.context.actorId)?.transfer;
     if (existingByActor !== undefined) {