@zlink-systems/framework 0.30.1 → 0.30.2

package/src/runtime/channels/channel-transports.ts

@@ -488,17 +488,15 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         metadata,
         correlationId
       );
-      const completion = await this.submitRequestOperation(
-        meshName,
-        timeoutMs,
-        signal,
-        `MeshNode '${meshName}' request to node '${targetNodeRid}'`,
-        (remainingTimeoutMs) => {
-          const operationId = node.requestToNode(toBackendRoutingId(targetNodeRid), parts, {
-            flags: 1,
-            onAdmitted,
-            timeoutMs: remainingTimeoutMs
-          });
+      const requestOptions = { flags: 1, onAdmitted, timeoutMs: requestTimeoutBudget(timeoutMs) };
+      let completion: ZLinkMeshCompletion;
+      try {
+        completion = await this.completionTable(meshName).submit(() => {
+          const operationId = node.requestToNode(
+            toBackendRoutingId(targetNodeRid),
+            parts,
+            requestOptions
+          );
           this.traceNodeRequest(
             ZLinkMessageFlowOutcome.Sent,
             undefined,
@@ -508,8 +506,13 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
             correlationId
           );
           return operationId;
-        }
-      );
+        }, signal);
+      } catch (error) {
+        throw mapMeshSubmissionError(
+          error,
+          `MeshNode '${meshName}' request to node '${targetNodeRid}'`
+        );
+      }
       const reply = this.decodeMeshReply<TReply>(meshName, completion);
       this.traceNodeRequest(
         ZLinkMessageFlowOutcome.ReplyReceived,
@@ -658,58 +661,34 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     );
     const metric = this.metrics?.startRequest(meshName, 'channel');
     try {
-      const completion = await this.submitRequestOperation(
-        meshName,
-        timeoutMs,
-        signal,
-        `MeshNode '${meshName}' request to channel '${channelName}'`,
-        (remainingTimeoutMs) =>
-          node.requestToChannel(channelName, parts, {
-            flags: 1,
-            timeoutMs: remainingTimeoutMs,
-            onAdmitted
-          })
-      );
+      const requestOptions = { flags: 1, timeoutMs: requestTimeoutBudget(timeoutMs), onAdmitted };
+      let completion: ZLinkMeshCompletion;
+      try {
+        completion = await this.completionTable(meshName).submit(
+          () => node.requestToChannel(channelName, parts, requestOptions),
+          signal
+        );
+      } catch (error) {
+        throw mapMeshSubmissionError(
+          error,
+          `MeshNode '${meshName}' request to channel '${channelName}'`
+        );
+      }
       const reply = this.decodeMeshReply<TReply>(meshName, completion);
       metric?.complete('completed');
       return reply;
     } catch (error) {
-      metric?.complete(requestMetricOutcome(error));
-      if (requestMetricOutcome(error) === 'target_not_found') {
+      metric?.complete(requestMetricOutcome(error, signal));
+      if (
+        error instanceof ZLinkFrameworkException &&
+        internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+      ) {
         this.metrics?.recordChannelSelectionFailure(meshName, channelName, 'no_ready_target');
       }
       throw error;
     }
   }
 
-  private async submitRequestOperation(
-    meshName: string,
-    timeoutMs: number | undefined,
-    signal: AbortSignal | undefined,
-    operation: string,
-    attempt: (
-      remainingTimeoutMs: number
-    ) => ReturnType<Parameters<ZLinkMeshCompletionTable['submit']>[0]>
-  ): Promise<ZLinkMeshCompletion> {
-    const effectiveTimeoutMs = Math.max(1, timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
-    const deadlineMs = performance.now() + effectiveTimeoutMs;
-    const remainingTimeoutMs = deadlineMs - performance.now();
-    if (remainingTimeoutMs <= 0) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-        `${operation} timed out before submission.`
-      );
-    }
-    try {
-      return await this.completionTable(meshName).submit(
-        () => attempt(Math.max(1, Math.ceil(remainingTimeoutMs))),
-        signal
-      );
-    } catch (error) {
-      throw mapMeshSubmissionError(error, operation);
-    }
-  }
-
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -1169,6 +1148,14 @@ function instanceSpotRouteFence(target: ZLinkSpotRouteTarget): ServiceInstanceRo
   };
 }
 
+/**
+ * The binding request timeout for one submission. The binding owns the
+ * deadline after submit; the completion table slot only waits for it.
+ */
+function requestTimeoutBudget(timeoutMs: number | undefined): number {
+  return Math.max(1, Math.ceil(timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+}
+
 function mapMeshSubmitResult(result: number): ZLinkSubmitResult {
   return classifySubmitResult(result, 'Mesh submission');
 }
@@ -1260,14 +1247,18 @@ export function meshRequestFailure(
   return error;
 }
 
-function requestMetricOutcome(error: unknown): string {
+function requestMetricOutcome(error: unknown, signal?: AbortSignal): string {
   if (error instanceof ZLinkFrameworkException) {
-    if (internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.RequestTargetNotFound)
-      return 'target_not_found';
     if (internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.DeadlineExceeded)
       return 'timed_out';
     if (internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.RuntimeShutdown)
       return 'shutdown';
   }
+  if (
+    signal?.aborted === true &&
+    (error === signal.reason ||
+      (error instanceof Error && (error.cause === signal.reason || error.name === 'AbortError')))
+  )
+    return 'cancelled';
   return 'failed';
 }

package/src/runtime/channels/client-server-location-runtime.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import type { Message } from '../../contracts/Common/Message';
 import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import {
@@ -121,9 +122,9 @@ export class ZLinkClientServerLocationRuntime {
         ownerId: owner.ownerId,
         leaseGeneration: owner.leaseGeneration
       };
-      const result = await this.store.updateClientServer(
-        candidate,
-        ZLinkLocationWriteIntent.Takeover,
+      const result = await this.locationRuntime.writeDescriptor(
+        (writeSignal) =>
+          this.store.updateClientServer(candidate, ZLinkLocationWriteIntent.Takeover, writeSignal),
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -152,9 +153,9 @@ export class ZLinkClientServerLocationRuntime {
                 descriptorRevision: current.descriptorRevision + 1n,
                 weight: runtimeWeight
               };
-        const result = await this.store.updateClientServer(
-          candidate,
-          ZLinkLocationWriteIntent.Renew,
+        const result = await this.locationRuntime.writeDescriptor(
+          (writeSignal) =>
+            this.store.updateClientServer(candidate, ZLinkLocationWriteIntent.Renew, writeSignal),
           signal
         );
         if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -181,9 +182,9 @@ export class ZLinkClientServerLocationRuntime {
         leaseGeneration: owner.leaseGeneration,
         updatedAt: new Date(0)
       };
-      const result = await this.store.updateClientServer(
-        descriptor,
-        ZLinkLocationWriteIntent.NewClaim,
+      const result = await this.locationRuntime.writeDescriptor(
+        (writeSignal) =>
+          this.store.updateClientServer(descriptor, ZLinkLocationWriteIntent.NewClaim, writeSignal),
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -587,7 +588,7 @@ function requireMatchingAdmission(
 ): void {
   if (
     actual.channelName !== expected.channelName ||
-    actual.serverRid !== String(expected.serverRid) ||
+    !routingIdsEqual(actual.serverRid, expected.serverRid) ||
     actual.lifecycleGeneration !== expected.lifecycleGeneration ||
     actual.descriptorRevision !== expected.descriptorRevision ||
     actual.weight !== expected.weight ||

package/src/runtime/channels/dispatch-error-reporter.ts

@@ -21,6 +21,7 @@ export type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port'
 
 type ZLinkRuntimeDispatchFailure = ZLinkDispatchFailure & {
   readonly error?: unknown;
+  readonly severity?: 'warning';
 };
 
 export class ZLinkDispatchErrorReporter {
@@ -37,7 +38,7 @@ export class ZLinkDispatchErrorReporter {
     _providerResolver: unknown,
     errorSink: ZLinkDispatchErrorSink,
     ctx?: ZLinkDiagnosticsContext,
-    private readonly metrics?: ZLinkRuntimeMetrics
+    readonly metrics?: ZLinkRuntimeMetrics
   ) {
     const flowCtx: ZLinkDiagnosticsContext = ctx ?? {
       diagnostics: DEFAULT_ZLINK_DIAGNOSTICS,
@@ -86,7 +87,8 @@ export class ZLinkDispatchErrorReporter {
       errorType: errorInfo.errorType,
       errorMessage: errorInfo.errorMessage,
       errorCauseType: errorInfo.errorCauseType,
-      errorCauseMessage: errorInfo.errorCauseMessage
+      errorCauseMessage: errorInfo.errorCauseMessage,
+      severity: normalized.severity
     });
   }
 

package/src/runtime/channels/fanout-location-runtime.ts

@@ -155,9 +155,13 @@ export class ZLinkFanoutLocationRuntime {
         ownerId: owner.ownerId,
         leaseGeneration: owner.leaseGeneration
       };
-      const result = await this.store.updateFanoutPublisher(
-        candidate,
-        ZLinkLocationWriteIntent.Takeover,
+      const result = await this.locationRuntime.writeDescriptor(
+        (writeSignal) =>
+          this.store.updateFanoutPublisher(
+            candidate,
+            ZLinkLocationWriteIntent.Takeover,
+            writeSignal
+          ),
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -188,9 +192,9 @@ export class ZLinkFanoutLocationRuntime {
       }
       const current = await this.lane.run(() => this.localDescriptors.get(channelName));
       if (current !== undefined) {
-        const result = await this.store.updateFanoutPublisher(
-          current,
-          ZLinkLocationWriteIntent.Renew,
+        const result = await this.locationRuntime.writeDescriptor(
+          (writeSignal) =>
+            this.store.updateFanoutPublisher(current, ZLinkLocationWriteIntent.Renew, writeSignal),
           signal
         );
         if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -231,9 +235,13 @@ export class ZLinkFanoutLocationRuntime {
         leaseGeneration: owner.leaseGeneration,
         updatedAt: new Date(0)
       };
-      const result = await this.store.updateFanoutPublisher(
-        descriptor,
-        ZLinkLocationWriteIntent.NewClaim,
+      const result = await this.locationRuntime.writeDescriptor(
+        (writeSignal) =>
+          this.store.updateFanoutPublisher(
+            descriptor,
+            ZLinkLocationWriteIntent.NewClaim,
+            writeSignal
+          ),
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {

package/src/runtime/diagnostics/flow-context.ts

@@ -2,7 +2,6 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomBytes } from 'node:crypto';
 import type { ZLinkFlowOrigin } from '../../contracts';
 const FLOW_UUID_BYTES = 16;
-const FLOW_UUID_VARIANT_BYTE = 8;
 
 /**
  * Spec 27 §3 defines the flow_origin value set as lowercase
@@ -97,13 +96,27 @@ export function createInboundFlow(
   return { flowId: flowId ?? createFlowId(), flowOrigin: flowOrigin ?? 'Inbound', streamSessionId };
 }
 
+/**
+ * UUIDv7 with a dedicated counter (RFC 9562 §6.2 method 1): the 48-bit
+ * millisecond timestamp, then a 42-bit counter that starts at a random value
+ * and spans `rand_a` and the top of `rand_b`, then 32 random bits drawn once
+ * per process. Flow ids stay unique within the process without drawing
+ * random bytes for every message.
+ */
+const flowRandom = randomBytes(FLOW_UUID_BYTES);
+const FLOW_COUNTER_SPAN = 2 ** 42;
+let flowCounter = flowRandom.readUIntBE(0, 6) % FLOW_COUNTER_SPAN;
+const FLOW_ID_TAIL = flowRandom.toString('hex', FLOW_UUID_BYTES - 4);
+
 function createFlowId(): string {
-  const bytes = randomBytes(FLOW_UUID_BYTES);
+  const counter = flowCounter;
+  flowCounter = (flowCounter + 1) % FLOW_COUNTER_SPAN;
   // Date.now() is always within 48 bits, which is exactly the UUIDv7
   // timestamp field.
-  bytes.writeUIntBE(Date.now(), 0, 6);
-  bytes[6] = 0x70 | (bytes[6] & 0x0f);
-  bytes[FLOW_UUID_VARIANT_BYTE] = 0x80 | (bytes[FLOW_UUID_VARIANT_BYTE] & 0x3f);
-  const hex = bytes.toString('hex');
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  const timestamp = Date.now().toString(16).padStart(12, '0');
+  const randA = Math.floor(counter / 2 ** 30); // 12 bits
+  const randB = counter % 2 ** 30; // 30 bits after the 2 variant bits
+  const variantHigh = (0x8000 | Math.floor(randB / 2 ** 16)).toString(16);
+  const randBLow = (randB % 2 ** 16).toString(16).padStart(4, '0');
+  return `${timestamp.slice(0, 8)}-${timestamp.slice(8)}-7${randA.toString(16).padStart(3, '0')}-${variantHigh}-${randBLow}${FLOW_ID_TAIL}`;
 }

package/src/runtime/diagnostics/index.ts

@@ -1,4 +1,3 @@
-import { AsyncResource } from 'node:async_hooks';
 import type {
   ZLinkLocationRuntimeQuery,
   ZLinkLocationRuntimeStatus,
@@ -18,7 +17,7 @@ import type {
   ZLinkSpotLocation
 } from '../../contracts/Locations/Rows';
 import type { ZLinkBackendSocketMonitor, ZLinkBackendSocketMonitorEvent } from '../backend';
-import { ZLinkStateLane } from '../execution/state-lane';
+import { startOutsideStateLane, ZLinkStateLane } from '../execution/state-lane';
 import { normalizeOpaqueRoutingId } from '../routing-id';
 import {
   ZLinkLocationActorEventKind as ActorLocationEventKind,
@@ -54,7 +53,6 @@ export {
 } from './internal-event-contracts';
 
 const ZLINK_DISCONNECT_REASON_HANDSHAKE_FAILED = 3;
-const detachedStateLaneResource = new AsyncResource('zlink:location-runtime-monitoring-source');
 
 export interface ZLinkActorOwnerLeaseObservation {
   readonly actorId: string;
@@ -461,10 +459,6 @@ async function publishLocationRuntimeChange<T>(
   await publisher.publish(runtimeEvent);
 }
 
-function startOutsideStateLane<T>(work: () => T): T {
-  return detachedStateLaneResource.runInAsyncScope(work);
-}
-
 function stableSnapshot(value: unknown): string {
   return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? item.toString() : item));
 }

package/src/runtime/diagnostics/message-flow.ts

@@ -13,7 +13,7 @@ import {
   type ZLinkRuntimeMessageFlowEvent,
   type ZLinkRuntimeMessageFlowResult
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import { ERROR_MESSAGE_MAX_LENGTH } from './dispatch-error-details';
+import { ERROR_MESSAGE_MAX_LENGTH, dispatchErrorDetails } from './dispatch-error-details';
 import type { ZLinkDispatchErrorSink } from './dispatch-error-port';
 import { currentFlowContext, FLOW_ORIGIN_VALUES } from './flow-context';
 const MESSAGE_FLOW_EVENT_ID = 'zlink.message_flow';
@@ -41,6 +41,7 @@ const telemetryTracer = openTelemetryTrace.getTracer('@zlink-systems/framework')
 let diagnosticsGeneration = 0n;
 
 interface ZLinkTelemetryRecord {
+  readonly severity?: 'warning';
   readonly eventId: typeof MESSAGE_FLOW_EVENT_ID | typeof DISPATCH_ERROR_EVENT_ID;
   readonly timestamp: Date;
   readonly phase?: string;
@@ -86,6 +87,15 @@ export function effectiveMessageFlow(ctx: ZLinkDiagnosticsContext): ZLinkMessage
   return ctx.liveMode.mode;
 }
 
+/**
+ * Message-flow tracing is on at Normal and Detailed only (04-flow-correlation
+ * §4). Below it no flow ID is created, validated, captured or propagated. This
+ * is the one decision every flow processing point reads.
+ */
+export function messageFlowTracingEnabled(mode: ZLinkMessageFlowLogMode): boolean {
+  return MESSAGE_FLOW_MODE_RANK[mode] >= MESSAGE_FLOW_MODE_RANK.normal;
+}
+
 export function createMessageFlowModeCell(
   dispatch: { diagnostics?: ZLinkDiagnosticsOptions } | undefined
 ): ZLinkMessageFlowModeCell {
@@ -137,10 +147,33 @@ export interface ZLinkMessageFlowTracePoint {
   trace(flowInput: MessageFlowInput): void;
 }
 
+export function traceSessionBindingControlDrop(
+  flow: ZLinkMessageFlowTracer | undefined,
+  sourceRid: string,
+  actorId: string,
+  packetName: string,
+  errorReason: 'location_unavailable' | 'stale_target',
+  error?: unknown
+): void {
+  const point = flowIfEnabled(flow, ZLinkMessageFlowOutcome.Dropped);
+  if (point === undefined) return;
+  point.trace({
+    outcome: ZLinkMessageFlowOutcome.Dropped,
+    surface: ZLinkDispatchErrorSurface.StreamSession,
+    messageKind: ZLinkDispatchMessageKind.Control,
+    sourceRid,
+    actorId,
+    packetName,
+    errorReason,
+    ...dispatchErrorDetails(error)
+  });
+}
+
 type MessageFlowInput = Omit<
   ZLinkRuntimeMessageFlowEvent,
   'effectiveMode' | 'flowId' | 'flowOrigin'
 > & {
+  readonly severity?: 'warning';
   readonly effectiveMode?: ZLinkMessageFlowLogMode;
   readonly flowId?: string;
   readonly flowOrigin?: import('../../contracts').ZLinkFlowOrigin;
@@ -201,7 +234,7 @@ export class ZLinkMessageFlowTracer {
   }
 
   flowCreationEnabled(): boolean {
-    return effectiveMessageFlow(this.ctx) !== 'off';
+    return messageFlowTracingEnabled(effectiveMessageFlow(this.ctx));
   }
 
   trace(flowInput: MessageFlowInput): void {
@@ -234,7 +267,7 @@ export class ZLinkMessageFlowTracer {
     const ambient = currentFlowContext();
     const flowId = flowInput.flowId ?? acceptedFlowId ?? ambient?.flowId;
     const flowOrigin = flowInput.flowOrigin ?? acceptedFlowOrigin ?? ambient?.flowOrigin;
-    const flow: ZLinkRuntimeMessageFlowEvent = {
+    const flow: MessageFlowInput = {
       ...flowInput,
       ...(flowId === undefined ? {} : { flowId, flowOrigin }),
       streamSessionId: flowInput.streamSessionId ?? ambient?.streamSessionId,
@@ -302,13 +335,17 @@ export class ZLinkMessageFlowTracer {
 
   private publishToLogger(record: ZLinkTelemetryRecord): void {
     try {
-      const severityNumber =
-        record.eventId === DISPATCH_ERROR_EVENT_ID ? SeverityNumber.ERROR : SeverityNumber.INFO;
+      const severity =
+        record.severity === 'warning'
+          ? 'WARN'
+          : record.eventId === DISPATCH_ERROR_EVENT_ID
+            ? 'ERROR'
+            : 'INFO';
       telemetryLogger.emit({
         eventName: record.eventId,
         timestamp: record.timestamp,
-        severityNumber,
-        severityText: record.eventId === DISPATCH_ERROR_EVENT_ID ? 'ERROR' : 'INFO',
+        severityNumber: SeverityNumber[severity],
+        severityText: severity,
         body: structuredLogBody(record),
         attributes: structuredLogAttributes(record)
       });
@@ -342,11 +379,12 @@ export class ZLinkMessageFlowTracer {
 }
 
 function toTelemetryRecord(
-  flow: ZLinkRuntimeMessageFlowEvent,
+  flow: MessageFlowInput,
   messageSizeBytes: number | undefined,
   durationSeconds: number | undefined
 ): ZLinkTelemetryRecord {
   return {
+    severity: flow.severity,
     eventId:
       flow.outcome === ZLinkMessageFlowOutcome.Error
         ? DISPATCH_ERROR_EVENT_ID
@@ -387,7 +425,7 @@ function toTelemetryRecord(
 function traceAttributes(record: ZLinkTelemetryRecord): Attributes {
   const attributes: Attributes = {};
   for (const [name, value] of Object.entries(record)) {
-    if (value === undefined || name === 'timestamp') continue;
+    if (value === undefined || name === 'timestamp' || name === 'severity') continue;
     attributes[toSnakeCase(name)] = value instanceof Date ? value.toISOString() : value;
   }
   return attributes;

package/src/runtime/diagnostics/runtime-metrics.ts

@@ -51,8 +51,8 @@ export interface ZLinkRuntimeMetricMeshSnapshot {
     readonly channelName: string;
     readonly readyMembers: number;
   }>;
-  readonly actorCapacity: ZLinkRuntimeMetricCapacity;
-  readonly spotCapacity: ZLinkRuntimeMetricCapacity;
+  readonly actorCapacity?: ZLinkRuntimeMetricCapacity;
+  readonly spotCapacity?: ZLinkRuntimeMetricCapacity;
   readonly spotTypeCapacities: ReadonlyArray<ZLinkRuntimeMetricSpotTypeCapacity>;
   readonly activation: { readonly active: number; readonly limit: number };
   readonly instanceSpots: ReadonlyArray<{
@@ -383,14 +383,16 @@ class MetricRegistry {
       }
     } else if (name.startsWith('zlink.object.capacity.')) {
       const field = metricSuffix(name);
-      result.observe(capacityValue(snapshot.actorCapacity, field), {
-        ...mesh,
-        capacity_scope: 'actor'
-      });
-      result.observe(capacityValue(snapshot.spotCapacity, field), {
-        ...mesh,
-        capacity_scope: 'spot'
-      });
+      if (snapshot.actorCapacity !== undefined)
+        result.observe(capacityValue(snapshot.actorCapacity, field), {
+          ...mesh,
+          capacity_scope: 'actor'
+        });
+      if (snapshot.spotCapacity !== undefined)
+        result.observe(capacityValue(snapshot.spotCapacity, field), {
+          ...mesh,
+          capacity_scope: 'spot'
+        });
     } else if (name.startsWith('zlink.spot.type.capacity.')) {
       const field = metricSuffix(name);
       for (const capacity of snapshot.spotTypeCapacities) {

package/src/runtime/execution/index.ts

@@ -1,5 +1,4 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { ZLinkConfigurationException } from '../configuration';
 import { isAbortError } from '../abort';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -53,6 +52,7 @@ export class ZLinkSpotSerialTurn {
   private suspendedResolve: (() => void) | undefined;
   private suspendedPromise: Promise<void> | undefined;
   private suspendSignaled = false;
+  private yieldUsed = false;
   private owner: Promise<unknown> | undefined;
   private frameworkOperationsBlocked = false;
 
@@ -115,26 +115,41 @@ export class ZLinkSpotSerialTurn {
   }
 
   resetSuspension(): void {
+    this.yieldUsed = false;
     this.suspendSignaled = false;
     this.suspendedResolve = undefined;
     this.suspendedPromise = undefined;
   }
 
-  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
-    if (!this.yieldAllowed) {
-      throw new ZLinkConfigurationException(
-        'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  admitYield(): void {
+    const current = spotSerialTurnStorage.getStore();
+    if (
+      current?.turn !== this ||
+      !this.yieldAllowed ||
+      !current.executor.isActiveTurn(this, current.turnId) ||
+      this.yieldUsed
+    ) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'Yield requires the current SpotWide application turn and may be used only once per turn.'
       );
     }
+    this.yieldUsed = true;
+  }
+
+  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
+    this.admitYield();
     return await this.yieldFrameworkPromise(pending);
   }
 
   /** Suspends a turn only for a Framework-owned lifecycle boundary. */
   async yieldFrameworkPromise<T>(pending: Promise<T>): Promise<T> {
     this.signalSuspended();
-    const result = await pending;
-    await this.awaitResumePermit();
-    return result;
+    try {
+      return await pending;
+    } finally {
+      await this.awaitResumePermit();
+    }
   }
 
   async resumeOwnerUntilNextYield(): Promise<void> {
@@ -204,16 +219,18 @@ export function currentZLinkSpotSerialSourceId(): unknown {
 
 export function requireZLinkYieldTurn(capturedTurn?: ZLinkSpotSerialTurn): ZLinkSpotSerialTurn {
   const turn = capturedTurn ?? captureZLinkSpotSerialTurn();
-  if (turn === undefined || !turn.yieldAllowed) {
-    throw new ZLinkConfigurationException(
-      'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  if (turn === undefined) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.InvalidOperation,
+      'Yield requires a current SpotWide application turn.'
     );
   }
+  turn.admitYield();
   return turn;
 }
 
 export interface ZLinkCapturedExecutionTurn {
-  yieldPromise<T>(pending: Promise<T>): Promise<T>;
+  yieldPromise<T>(operation: () => Promise<T>): Promise<T>;
   post(callback: () => void): void;
 }
 
@@ -223,7 +240,16 @@ export function captureZLinkExecutionTurn(): ZLinkCapturedExecutionTurn | undefi
     return undefined;
   }
   return {
-    yieldPromise: <T>(pending: Promise<T>) => current.turn.yieldPromise(pending),
+    yieldPromise: <T>(operation: () => Promise<T>) => {
+      const turn = requireZLinkYieldTurn(current.turn);
+      let pending: Promise<T>;
+      try {
+        pending = operation();
+      } catch (error) {
+        pending = Promise.reject(error);
+      }
+      return turn.yieldFrameworkPromise(pending);
+    },
     post: (callback: () => void) => {
       void current.executor.post(callback);
     }
@@ -241,7 +267,7 @@ export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecut
 
 export interface ZLinkExecutionBarrierSeal {
   readonly generation: bigint;
-  readonly kind: 'close' | 'relocation';
+  readonly kind: 'close' | 'relocation' | 'activation';
 }
 
 export interface ZLinkExecutionBarrierClaim {