@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -1,3 +1,6 @@
+import { routingIdsEqual } from '../../routing-id';
+import { requestDurableService } from '../../foundation/durable-service-request';
+import { encodeRoutingIdStorageHex, toBackendRoutingId } from '../../routing-id';
 import {
   decodeStreamWireFrame,
   decodeStreamWireHeader,
@@ -19,7 +22,11 @@ import {
 import { randomBytes } from 'node:crypto';
 import type { ZLinkMeshCompletionHandler } from '../mesh-completion-table';
 import { setImmediate as yieldToIO } from 'node:timers/promises';
-import { type RoutingId, ZLinkFrameworkException } from '../../../contracts';
+import {
+  type RoutingId,
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind
+} from '../../../contracts';
 
 import type { Message as FrameworkMessage } from '../../../contracts/Common/Message';
 import { ZLinkConfigurationException } from '../../../contracts/Configuration/ConfigurationException';
@@ -43,6 +50,8 @@ import {
 import {
   RawServiceMeshRuntime,
   RAW_MESH_RECEIVE_TIME_BUDGET_MS,
+  type RawServiceObservedRequest,
+  type RawServiceRequestObserver,
   type RawServiceRequestResult
 } from '../../foundation/raw-service-mesh-runtime';
 import type { ServiceInstanceActivationRecoveryEnvelope } from '../../foundation/service-instance-activation-recovery-codec';
@@ -80,6 +89,7 @@ import {
   type ServiceAsyncInstanceActivationAuthority,
   type ServiceInstanceApplicationLifecycle,
   type ServicePendingInstanceActivation,
+  type ServiceSessionOwnerDescriptors,
   type ServiceSpotMessageFollowSeal,
   type ServiceStatefulMailboxData,
   type ServiceStatefulPendingOperation,
@@ -111,9 +121,10 @@ import {
   ServiceWireFrameworkErrorCode
 } from '../../foundation/service-wire-constants.generated';
 import {
-  APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES,
-  APPLICATION_PAYLOAD_VERSION,
   decodeApplicationPayloadView,
+  decodeMultipartApplicationPayloadView,
+  decodeMultipartApplicationParts,
+  decodeMultipartParts,
   encodeMultipartApplicationPayload,
   ServiceWireProtocolError,
   type ServiceApplicationPayload
@@ -132,18 +143,20 @@ import {
   ZLinkBackendResultError,
   type ZLinkBackendMessageLike as MessageLike
 } from '../runtime-values';
-import { translateBindingResultError } from './node-backend-adapter-support';
-import { disconnectStreamPeer } from './node-socket-backend-adapter';
+import { translateBindingResultError, toNativeRoutingId } from './node-backend-adapter-support';
+import { disconnectSocketPeer } from './node-socket-backend-adapter';
 const DEFAULT_NATIVE_ACTIVE_CAPACITY = 10_000;
 const UNSTARTED_DIAGNOSTIC_ENDPOINT = 'inproc://not-started';
 
 const MULTIPART_PACKET_NAME = SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME;
 const MULTIPART_CONTENT_TYPE = SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE;
-const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 const MAX_DRAIN_RECORDS = 64;
-// Preserve the existing route observation/admission/liveness cadence. Only the binding
-// readable handler admits receive work; this timer never probes the socket.
+// The maintenance timer runs at the nearest management deadline and never
+// sooner than this. Only the binding readable handler admits receive work;
+// this timer never probes the socket.
 const MESH_BACKEND_MAINTENANCE_INTERVAL_MS = 1;
+/** The longest single timer delay Node accepts. */
+const MESH_BACKEND_MAINTENANCE_MAX_DELAY_MS = 2 ** 31 - 1;
 // Spec 08 §4.2 bounds the combined turn. Raw gets one equal share; stateful
 // can use the remaining turn, including time the raw registry did not consume.
 const MESH_BACKEND_RAW_MAINTENANCE_SHARE = 1 / 2;
@@ -172,7 +185,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     }
   >();
   private completionHandler?: ZLinkMeshCompletionHandler;
-  private readonly routingId: string;
+  readonly routingId: string;
   private readonly lifecycleGeneration: bigint;
   private bindEndpoint?: string;
   private advertiseHost?: string;
@@ -180,15 +193,17 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   private stateful?: ServiceStatefulRuntime;
   private readyHandler?: (domains: number) => number;
   private maintenanceTimer?: NodeJS.Timeout;
-  private pumping = false;
+  private maintenanceDueMs = Number.POSITIVE_INFINITY;
+  private pumpTask?: Promise<void>;
   private readable = 0;
   private readonly onReadable = (receiveReady: boolean, routeReady: boolean): void => {
     if (receiveReady) this.readable |= 1;
     if (routeReady) this.readable |= 2;
-    if (!this.closed && !this.pumping) void this.pump();
+    this.pump();
   };
   private readonly onMaintenance = (): void => {
     this.maintenanceTimer = undefined;
+    this.maintenanceDueMs = Number.POSITIVE_INFINITY;
     if (this.closed) return;
     const nowMs = performance.now();
     const turnDeadlineMs = nowMs + RAW_MESH_RECEIVE_TIME_BUDGET_MS;
@@ -198,7 +213,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     );
     this.stateful?.expireOperations(nowMs, turnDeadlineMs);
     this.scheduleMaintenance();
-    void this.pump();
+    this.pump();
   };
   private readonly onPendingOperationsChanged = (): void => this.scheduleMaintenance();
   private nextPeerIntent = 1n;
@@ -223,6 +238,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     record: import('../../foundation/service-stateful-wire-codec').ServiceMessageFollowRecord
   ) => void;
   private dispatchErrors?: ZLinkDispatchErrorReporter;
+  private sessionOwnerDescriptors?: ServiceSessionOwnerDescriptors;
+  private requestSourceAcceptance?: import('../contracts').ZLinkBackendRequestSourceAcceptance;
   private readonly peerDisconnectedHandlers = new Set<(endpoint: string) => void>();
   constructor(
     private readonly meshName: string,
@@ -279,6 +296,11 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.stateful?.setDispatchErrorReporter(reporter, this.meshName);
   }
 
+  setSessionOwnerDescriptors(source: ServiceSessionOwnerDescriptors): void {
+    this.sessionOwnerDescriptors = source;
+    this.stateful?.setSessionOwnerDescriptors(source);
+  }
+
   setProtocolErrorHandler(
     handler: (record: {
       readonly sourceNodeRid: string;
@@ -342,7 +364,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     parts: MessageLike | readonly MessageLike[],
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.InstanceSpotRequest,
@@ -351,13 +374,14 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         encodeMultipartApplicationFrame(parts),
         deadlineUnixMs,
         sourceSpotId,
-        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata)
+        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
+        onAdmitted
       )
     );
   }
 
   setRoutingId(routingId: unknown): void {
-    if (String(routingId) !== this.routingId) {
+    if (!routingIdsEqual(toBackendRoutingId(routingId), this.routingId)) {
       throw new Error('MeshNode routing id is immutable after construction.');
     }
   }
@@ -411,15 +435,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
           }
         }
       },
-      onPeerDisconnected: (nodeRoutingId, endpoint) => {
-        for (const [intentId, peer] of this.peerIntents) {
-          if (
-            peer.endpoint === endpoint &&
-            (peer.nodeRoutingId === undefined || peer.nodeRoutingId === nodeRoutingId)
-          ) {
-            this.peerIntents.delete(intentId);
-          }
-        }
+      onPeerDisconnected: (_nodeRoutingId, endpoint) => {
         for (const handler of this.peerDisconnectedHandlers) handler(endpoint);
       }
     });
@@ -433,15 +449,21 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     if (this.dispatchErrors !== undefined) {
       this.stateful.setDispatchErrorReporter(this.dispatchErrors, this.meshName);
     }
+    if (this.sessionOwnerDescriptors !== undefined) {
+      this.stateful.setSessionOwnerDescriptors(this.sessionOwnerDescriptors);
+    }
     if (this.mailboxRecordDropped !== undefined) {
       this.stateful.setMailboxDropHandler(this.mailboxRecordDropped);
     }
     this.stateful.setMessageFollowHandler((record) => this.messageFollowHandler?.(record));
+    if (this.requestSourceAcceptance !== undefined) {
+      this.stateful.setRequestSourceAcceptance(this.requestSourceAcceptance);
+    }
     this.runtime = runtime;
     try {
       runtime.setReadableHandler(this.onReadable);
     } catch (error) {
-      this.close();
+      void this.close().catch((failure) => runtime.reportInfrastructureFailure(failure));
       throw error;
     }
     this.scheduleMaintenance();
@@ -465,25 +487,30 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return await this.requireStateful().sendMessageFollowNotification(targetNodeRid, record);
   }
 
-  shutdown(_timeoutMs: number): RequestResultValue {
-    this.close();
+  async shutdown(_timeoutMs: number): Promise<RequestResultValue> {
+    await this.close();
     return RequestResult.Ok;
   }
 
+  cancelPendingOperations(reason: unknown): void {
+    this.stateful?.cancelPendingOperations(reason);
+    this.runtime?.cancelPendingOperations(reason);
+  }
+
   async publishDraining(): Promise<void> {
     for (const name of this.channels.keys()) this.channels.set(name, 0);
     await this.requireRuntime().updateLocalDescriptor({ state: 'draining' });
   }
 
-  close(): void {
-    if (this.closed) return;
+  async close(): Promise<void> {
+    this.closed = true;
     if (this.maintenanceTimer !== undefined) clearTimeout(this.maintenanceTimer);
     this.maintenanceTimer = undefined;
+    if (this.pumpTask !== undefined) await this.pumpTask;
     this.stateful?.close();
     this.stateful = undefined;
     this.runtime?.close();
     this.runtime = undefined;
-    this.closed = true;
   }
 
   addChannelName(name: string): void {
@@ -546,6 +573,13 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return intent;
   }
 
+  setRequestSourceAcceptance(
+    acceptance: import('../contracts').ZLinkBackendRequestSourceAcceptance
+  ): void {
+    this.requestSourceAcceptance = acceptance;
+    this.stateful?.setRequestSourceAcceptance(acceptance);
+  }
+
   expectPeer(peer: {
     readonly nodeRoutingId: string;
     readonly endpoint: string;
@@ -630,20 +664,52 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return this.requireRuntime().isObjectClientNodeDirectTarget(String(targetRid));
   }
 
+  waitForPeerRoute(
+    targetRid: unknown,
+    lifecycleGeneration: bigint,
+    deadlineUnixMs: bigint,
+    signal?: AbortSignal
+  ): Promise<void> {
+    return this.requireRuntime().waitForPeerRoute(
+      String(targetRid),
+      lifecycleGeneration,
+      deadlineUnixMs,
+      signal
+    );
+  }
+
+  observePeerRoute(targetRid: unknown) {
+    return this.requireRuntime().observePeerRoute(String(targetRid));
+  }
+
+  hasPeerRouteOrConnectionIntent(targetRid: unknown, endpoint: string): boolean {
+    const rid = String(targetRid);
+    if (this.requireRuntime().hasSelectedPeerRoute(rid)) return true;
+    for (const intent of this.peerIntents.values()) {
+      if (
+        intent.nodeRoutingId === rid ||
+        (intent.nodeRoutingId === undefined && intent.endpoint === endpoint)
+      )
+        return true;
+    }
+    return false;
+  }
+
   isPeerRouteReady(targetRid: unknown, lifecycleGeneration?: bigint): boolean {
     return this.requireRuntime().isPeerRouteReady(String(targetRid), lifecycleGeneration);
   }
 
-  async sendToNode(
+  sendToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[]
-  ): Promise<SubmitResultValue> {
-    return (await this.requireRuntime().sendToNode(
+  ): SubmitResultValue | Promise<SubmitResultValue> {
+    const submitted = this.requireRuntime().sendToNode(
       String(targetRid),
       encodeMultipartApplicationFrame(parts)
-    ))
-      ? SubmitResult.Ok
-      : SubmitResult.NotConnected;
+    );
+    return submitted instanceof Promise
+      ? submitted.then(nodeSendResult)
+      : nodeSendResult(submitted);
   }
 
   async sendInfrastructureControl(
@@ -673,26 +739,37 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   async requestInfrastructureControlFrames(
     targetRid: unknown,
     frames: readonly Uint8Array[],
-    options?: { readonly timeoutMs?: number }
+    options?: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onSubmitted?: (signal: AbortSignal) => Promise<void>;
+    }
   ): Promise<readonly Uint8Array[]> {
-    return await this.requireRuntime().requestService(
+    return requestDurableService(
+      this.requireRuntime(),
       String(targetRid),
-      frames.map((frame) => Buffer.from(frame)),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      frames,
+      performance.now() + (options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS),
+      'relocation control',
+      options?.signal,
+      options?.onSubmitted
     );
   }
 
   requestToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     const pending = this.requireRuntime().requestToNode(
       String(targetRid),
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted,
+      this.requestObserver,
+      OperationKind.NodeRequest
     );
-    return this.observeCompletion(pending.id, OperationKind.NodeRequest, pending.promise);
+    return this.observedOperation(pending, OperationKind.NodeRequest);
   }
 
   async sendToChannel(
@@ -705,14 +782,17 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     const pending = this.requireRuntime().requestToChannel(
       channelName,
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted,
+      this.requestObserver,
+      OperationKind.ChannelRequest
     );
-    return this.observeCompletion(pending.id, OperationKind.ChannelRequest, pending.promise);
+    return this.observedOperation(pending, OperationKind.ChannelRequest);
   }
 
   status() {
@@ -918,7 +998,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   }
 
   waitForInstanceApplicationQuiescence(spotId: string, signal?: AbortSignal): Promise<void> {
-    return this.requireStateful().waitForInstanceApplicationQuiescence(spotId, signal);
+    // Closing the stateful owner terminalizes its operations and clears these waiters.
+    return this.stateful?.waitForInstanceApplicationQuiescence(spotId, signal) ?? Promise.resolve();
   }
 
   restoreUserSpotAuthority(
@@ -1004,7 +1085,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         generation: actor.generation
       },
       String(sessionNodeRid),
-      String(sessionRid),
+      toBackendRoutingId(sessionRid),
       bindingGeneration
     );
   }
@@ -1136,7 +1217,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
 
   commitSpotMessageFollowIngress(
     seal: ServiceSpotMessageFollowSeal,
-    target: ServiceDirectSpotRouteFence,
+    target: ServiceDirectSpotRouteFence | null,
     durationMs: number
   ): Promise<boolean> {
     return this.requireStateful().commitSpotMessageFollowIngress(seal, target, durationMs);
@@ -1173,7 +1254,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     sourceSpotId?: string,
     metadata?: ReadonlyMap<string, string>,
-    instanceIntent = false
+    instanceIntent = false,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.InstanceSpotRequest,
@@ -1183,7 +1265,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         timeoutMs,
         sourceSpotId,
         metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
-        instanceIntent
+        instanceIntent,
+        onAdmitted
       )
     );
   }
@@ -1315,33 +1398,52 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
 
   async sendToActor(
     actor: ZLinkBackendActorRef,
-    parts: MessageLike | readonly MessageLike[]
+    parts: MessageLike | readonly MessageLike[],
+    options?: {
+      readonly flags?: number;
+      readonly routeFence?: import('../../foundation/service-stateful-wire-codec').ServiceActorRouteFence;
+    }
   ): Promise<SubmitResultValue> {
     return this.requireStateful().sendToActor(
       actor,
-      this.peerGeneration(String(actor.nodeRid)),
-      actor.generation,
-      encodeMultipart(parts)
+      encodeMultipart(parts),
+      undefined,
+      undefined,
+      options?.routeFence
     ) as Promise<SubmitResultValue>;
   }
 
   requestToActor(
     actor: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: {
+      readonly timeoutMs?: number;
+      readonly onAdmitted?: () => void;
+      readonly routeFence?: import('../../foundation/service-stateful-wire-codec').ServiceActorRouteFence;
+    }
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorRequest,
       this.requireStateful().requestToActor(
         actor,
-        this.peerGeneration(String(actor.nodeRid)),
-        actor.generation,
         encodeMultipart(parts),
-        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        undefined,
+        undefined,
+        options?.onAdmitted,
+        options?.routeFence
       )
     );
   }
 
+  acceptRelocatedActorTerminal(
+    operation: { readonly high: bigint; readonly low: bigint },
+    replyRouteId: bigint,
+    result: import('../../foundation/service-stateful-runtime').ServiceStatefulResult
+  ): 'terminalReceived' | 'alreadyTerminal' | undefined {
+    return this.requireStateful().acceptRelocatedActorTerminal(operation, replyRouteId, result);
+  }
+
   async actorSendToActor(
     source: ZLinkBackendActorRef,
     target: ZLinkBackendActorRef,
@@ -1349,8 +1451,6 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   ): Promise<SubmitResultValue> {
     return (await this.requireStateful().sendToActor(
       target,
-      this.peerGeneration(String(target.nodeRid)),
-      target.generation,
       encodeMultipart(parts),
       source
     )) as SubmitResultValue;
@@ -1360,17 +1460,17 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     source: ZLinkBackendActorRef,
     target: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorRequest,
       this.requireStateful().requestToActor(
         target,
-        this.peerGeneration(String(target.nodeRid)),
-        target.generation,
         encodeMultipart(parts),
         options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-        source
+        source,
+        undefined,
+        options?.onAdmitted
       )
     );
   }
@@ -1393,18 +1493,9 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     expectedBindingGeneration: bigint,
     timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
-    const binding = this.requireStateful().registry.binding(actor);
-    if (binding === undefined) {
-      return this.observeImmediateFailure(OperationKind.StreamUnbind, RequestResult.NotFound);
-    }
     return this.observeStateful(
       OperationKind.StreamUnbind,
-      this.requireStateful().unbindSession(
-        binding.sessionRid,
-        actor,
-        expectedBindingGeneration,
-        timeoutMs
-      )
+      this.requireStateful().closeBoundSession(actor, expectedBindingGeneration, timeoutMs)
     );
   }
 
@@ -1443,7 +1534,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     source: ServiceSpotState,
     target: ServiceDirectSpotRouteFence,
     parts: MessageLike | readonly MessageLike[],
-    timeoutMs: number
+    timeoutMs: number,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.SpotRequest,
@@ -1451,7 +1543,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         source.ref.spotId,
         target,
         encodeMultipart(parts),
-        timeoutMs
+        timeoutMs,
+        onAdmitted
       )
     );
   }
@@ -1475,6 +1568,11 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   }
 
   setSpotSubscription(state: ServiceSpotState, channelName: string, topicFilter: string): void {
+    if (!this.channels.has(channelName))
+      throw new ZLinkFrameworkException(
+        ZLinkFrameworkErrorKind.InvalidOperation,
+        `Spot does not participate in subscription channel '${channelName}'.`
+      );
     this.requireStateful().setSubscription(state, channelName, topicFilter);
   }
 
@@ -1522,9 +1620,35 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return result;
   }
 
+  /**
+   * Arms the one maintenance timer for the nearest management deadline
+   * (spec 08 §4.2): request expiry, liveness, or a pending peer handshake.
+   * An earlier deadline re-arms it; a later one keeps the armed time.
+   */
   private scheduleMaintenance(): void {
     if (this.closed) return;
-    this.maintenanceTimer ??= setTimeout(this.onMaintenance, MESH_BACKEND_MAINTENANCE_INTERVAL_MS);
+    const nowMs = performance.now();
+    const dueMs = Math.max(
+      nowMs + MESH_BACKEND_MAINTENANCE_INTERVAL_MS,
+      Math.min(
+        this.runtime?.nextMaintenanceDeadlineMs(nowMs) ?? Number.POSITIVE_INFINITY,
+        this.stateful?.nextMaintenanceDeadlineMs() ?? Number.POSITIVE_INFINITY
+      )
+    );
+    if (dueMs === Number.POSITIVE_INFINITY) {
+      if (this.maintenanceTimer !== undefined) clearTimeout(this.maintenanceTimer);
+      this.maintenanceTimer = undefined;
+      this.maintenanceDueMs = dueMs;
+      return;
+    }
+    if (this.maintenanceTimer === undefined || dueMs < this.maintenanceDueMs) {
+      if (this.maintenanceTimer !== undefined) clearTimeout(this.maintenanceTimer);
+      this.maintenanceTimer = setTimeout(
+        this.onMaintenance,
+        Math.min(MESH_BACKEND_MAINTENANCE_MAX_DELAY_MS, Math.ceil(dueMs - nowMs))
+      );
+      this.maintenanceDueMs = dueMs;
+    }
     const pending =
       (this.runtime?.pendingOperationCount ?? 0) + (this.stateful?.pendingOperationCount ?? 0) > 0;
     if (pending === this.maintenanceTimer.hasRef()) return;
@@ -1535,14 +1659,19 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     }
   }
 
-  private async pump(): Promise<void> {
-    if (this.isClosed() || this.pumping) return;
-    this.pumping = true;
+  private pump(): void {
+    if (this.closed || this.pumpTask !== undefined) return;
+    this.pumpTask = this.runPump(this.requireRuntime());
+  }
+
+  private async runPump(runtime: RawServiceMeshRuntime): Promise<void> {
+    // Publish pumpTask before any callback can signal readiness or begin close.
+    await Promise.resolve();
     try {
       do {
         const ready = this.readable;
         this.readable = 0;
-        const more = await this.requireRuntime().pumpBatch((ready & 1) !== 0, (ready & 2) !== 0);
+        const more = await runtime.pumpBatch((ready & 1) !== 0, (ready & 2) !== 0);
         if (more) {
           // Yield only after actual progress, retaining readiness across the
           // existing batch limits until receive reports no data.
@@ -1550,16 +1679,14 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
           await yieldToIO();
         }
       } while (!this.closed && this.readable !== 0);
+    } catch (error) {
+      runtime.reportInfrastructureFailure(error);
     } finally {
-      this.pumping = false;
+      this.pumpTask = undefined;
       this.scheduleMaintenance();
     }
   }
 
-  private isClosed(): boolean {
-    return this.closed;
-  }
-
   private notifyReady(): void {
     const runtime = this.runtime;
     let domains = ReadyDomain.None;
@@ -1572,6 +1699,26 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     if (domains !== ReadyDomain.None) this.readyHandler?.(domains);
   }
 
+  /**
+   * The raw registry takes a remote request's terminal and hands it here,
+   * where the Framework completion owner receives it in the same turn.
+   */
+  private readonly requestObserver: RawServiceRequestObserver = {
+    operationCompleted: (id, result, operationKind) =>
+      this.deliverCompletion({ high: 1n, low: id }, operationKind ?? 0, result),
+    operationFailed: (id, error, operationKind) =>
+      this.deliverCompletion({ high: 1n, low: id }, operationKind ?? 0, requestFailureResult(error))
+  };
+
+  private observedOperation(
+    pending: RawServiceObservedRequest,
+    operationKind: number
+  ): MeshOperationId {
+    return pending.promise === undefined
+      ? { high: 1n, low: pending.id }
+      : this.observeCompletion(pending.id, operationKind, pending.promise);
+  }
+
   private observeCompletion(
     low: bigint,
     operationKind: number,
@@ -1597,15 +1744,6 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return id;
   }
 
-  private observeImmediateFailure(operationKind: number, terminalResult: number): MeshOperationId {
-    const low = this.nextPeerIntent++;
-    return this.observeCompletion(
-      low,
-      operationKind,
-      Promise.resolve({ terminalResult, failureCode: 0 })
-    );
-  }
-
   private deliverCompletion(
     operationId: MeshOperationId,
     operationKind: number,
@@ -1719,7 +1857,11 @@ class RawServiceSpot implements ServiceSpot {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly flags?: number; readonly timeoutMs?: number }
+    options?: {
+      readonly flags?: number;
+      readonly timeoutMs?: number;
+      readonly onAdmitted?: () => void;
+    }
   ): MeshOperationId {
     this.requireOpen();
     return this.backend.requestToChannel(channelName, parts, options);
@@ -1755,6 +1897,7 @@ class RawServiceSpot implements ServiceSpot {
     parts: MessageLike | readonly MessageLike[],
     options?: {
       readonly timeoutMs?: number;
+      readonly onAdmitted?: () => void;
       readonly routeFence?: ServiceDirectSpotRouteFence;
       readonly entrySpot?: boolean;
     }
@@ -1773,7 +1916,8 @@ class RawServiceSpot implements ServiceSpot {
       this.state,
       routeFence,
       parts,
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted
     );
   }
 
@@ -1823,6 +1967,10 @@ class RawServiceSpot implements ServiceSpot {
   }
 }
 
+function nodeSendResult(submitted: boolean): SubmitResultValue {
+  return submitted ? SubmitResult.Ok : SubmitResult.NotConnected;
+}
+
 function requireDirectSpotRouteFence(
   route: ServiceDirectSpotRouteFence | undefined,
   targetNodeRid: string,
@@ -1884,7 +2032,9 @@ class RawStreamSessionService implements StreamSessionService {
     return {
       state: this.state,
       lifecycleGeneration: 1n,
-      sessionCount: BigInt(new Set(bindings.map((value) => value.sessionRid)).size),
+      sessionCount: BigInt(
+        new Set(bindings.map((value) => encodeRoutingIdStorageHex(value.sessionRid))).size
+      ),
       bindingCount: BigInt(bindings.length),
       pendingMessageCount: 0n,
       pendingByteCount: 0n,
@@ -1913,7 +2063,8 @@ class RawStreamSessionService implements StreamSessionService {
       retiredSession: ServiceRetiredBoundSessionRouteFence,
       actor: ServiceActorRef
     ) => void,
-    actorAuthority?: StreamSessionActorAuthorityFence
+    actorAuthority?: StreamSessionActorAuthorityFence,
+    close?: () => Promise<void>
   ): MeshOperationId {
     this.requireStarted();
     const sessionKey = String(sessionRid);
@@ -1921,13 +2072,13 @@ class RawStreamSessionService implements StreamSessionService {
     return this.observe(
       OperationKind.StreamBind,
       this.stateful.bindSession(
-        sessionKey,
+        sessionRid,
         actor,
         timeoutMs,
-        (targetSessionRid, payloadFrame) =>
-          this.deliver(targetSessionRid, actor.actorId, payloadFrame),
+        (_targetSessionRid, payloadFrame) => this.deliver(sessionKey, actor.actorId, payloadFrame),
         onBindingReplaced,
-        actorAuthority
+        actorAuthority,
+        close
       )
     );
   }
@@ -1941,12 +2092,12 @@ class RawStreamSessionService implements StreamSessionService {
     this.requireStarted();
     return this.observe(
       OperationKind.StreamUnbind,
-      this.stateful.unbindSession(String(sessionRid), actor, expectedBindingGeneration, timeoutMs)
+      this.stateful.unbindSession(sessionRid, actor, expectedBindingGeneration, timeoutMs)
     );
   }
 
   bindings(sessionRid: RoutingId) {
-    return this.stateful.sessionBindings(String(sessionRid));
+    return this.stateful.sessionBindings(sessionRid);
   }
 
   async sendToActor(
@@ -1956,7 +2107,7 @@ class RawStreamSessionService implements StreamSessionService {
   ): Promise<SubmitResultValue> {
     this.requireStarted();
     return (await this.stateful.sendSessionToActor(
-      String(sessionRid),
+      sessionRid,
       actor,
       encodeMultipart(parts)
     )) as SubmitResultValue;
@@ -1970,11 +2121,14 @@ class RawStreamSessionService implements StreamSessionService {
     const target = this.sessionTargets.get(sessionRid);
     if (target === undefined) return false;
     const operation = this.stream.send(target as unknown as BindingRoutingId);
-    const parts = decodeMultipartBuffers(decodeApplicationPayloadView(payload).payload);
+    const parts = decodeMultipartParts(
+      decodeApplicationPayloadView(payload).payload,
+      borrowMultipartPart
+    );
     if (parts.length === 0) return false;
     const actorSlot = await serviceSessionBindingIngressPortIfRegistered(this)?.actorSlot(
       actorId,
-      sessionRid
+      target
     );
     if (actorSlot === undefined) return false;
     parts[0] = Buffer.from(streamFrameWithActorSlot(parts[0]!, actorSlot));
@@ -1993,7 +2147,7 @@ class RawStreamSessionService implements StreamSessionService {
         case SubmitResult.Terminated:
           // Let the socket monitor drive the existing STREAM close/unbind
           // lifecycle instead of maintaining a second session-close state.
-          disconnectStreamPeer(this.stream, target);
+          disconnectSocketPeer(this.stream, toNativeRoutingId(target));
           throw new ZLinkBackendResultError('submit', error.result, error.nativeErrno, {
             cause: error
           });
@@ -2242,7 +2396,11 @@ function decodeMultipartRecord(
   const header = record.parts[0]!;
   const command = header[SERVICE_WIRE_COMMAND_OFFSET]!;
   const payloadFrame = record.parts[1]!;
-  const application = decodeApplicationEnvelope(payloadFrame);
+  const parts = decodeMultipartApplicationParts(
+    payloadFrame,
+    ZLinkBufferMessage.fromOwned,
+    closeMultipartMessage
+  );
   const channelName = record.owner.startsWith('channel:')
     ? record.owner.slice('channel:'.length)
     : null;
@@ -2264,7 +2422,7 @@ function decodeMultipartRecord(
       : kind === ReceiveKind.ChannelRequest
         ? OperationKind.ChannelRequest
         : 0;
-  const ingressLifecycle = receiveIngressLifecycle(record);
+  const applicationJob = record.applicationJob;
   return {
     kind,
     domain: readyDomain(record.domain),
@@ -2277,22 +2435,38 @@ function decodeMultipartRecord(
     channelName,
     topic: null,
     applicationMetadata: null,
-    packetName: application.packetName,
-    contentType: application.contentType,
+    packetName: SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
+    contentType: SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
     kindData: null,
     terminalResult: 0,
     failureErrno: 0,
-    ...ingressLifecycle,
-    parts: decodeMultipart(application.payload),
+    applicationJobPermit: applicationJob,
+    releaseRetainedIngress: applicationJob === undefined ? undefined : releaseRecordApplicationJob,
+    parts,
     reply(parts) {
       if (record.correlation === undefined) return SubmitResult.InvalidState;
       runtime.reply(record, encodeMultipartApplicationFrame(parts));
       return SubmitResult.Ok;
     },
-    replyActorJoin: () => SubmitResult.NotSupported
+    replyActorJoin: replyActorJoinNotSupported
   };
 }
 
+/** Shared by every ordinary record: the record's own permit lease is its retained ingress. */
+function releaseRecordApplicationJob(this: {
+  readonly applicationJobPermit?: import('../../application-jobs/contracts').ApplicationJobPermitPort;
+}): void {
+  (
+    this.applicationJobPermit as
+      | import('../../application-jobs/application-ingress-record-owner').ApplicationJobRecordLease
+      | undefined
+  )?.close();
+}
+
+function replyActorJoinNotSupported(): SubmitResultValue {
+  return SubmitResult.NotSupported;
+}
+
 function decodeStatefulRecord(
   record: ServiceMailboxRecord,
   stateful: ServiceStatefulMailboxData
@@ -2308,7 +2482,7 @@ function decodeStatefulRecord(
     ? stateful.canonicalApplicationPayload
     : payloadFrame === undefined
       ? undefined
-      : decodeApplicationEnvelope(payloadFrame);
+      : decodeMultipartApplicationPayloadView(payloadFrame);
   const operationId =
     record.correlation === undefined
       ? { high: 0n, low: 0n }
@@ -2316,6 +2490,12 @@ function decodeStatefulRecord(
   const ingressLifecycle = receiveIngressLifecycle(record);
   return {
     kind: stateful.receiveKind,
+    get requestSource() {
+      return record.requestSource;
+    },
+    prepareDispatch:
+      record.sourcePreparationOwner === undefined ? undefined : prepareStatefulMailboxDispatch,
+    statefulMailboxRecord: record,
     domain: readyDomain(record.domain),
     sourceNodeRid: (record.sourceRoutingId as RoutingId | undefined) ?? null,
     sourceSpotId: (stateful.sourceSpotId as RoutingId | undefined) ?? null,
@@ -2414,6 +2594,17 @@ function receiveIngressLifecycle(record: ServiceMailboxRecord): {
       };
 }
 
+function prepareStatefulMailboxDispatch(
+  this: import('../../foundation/service-runtime-contracts').ReceiveRecord,
+  signal: AbortSignal
+): boolean | Promise<boolean> {
+  const mailboxRecord = this.statefulMailboxRecord;
+  const owner = mailboxRecord?.sourcePreparationOwner;
+  return mailboxRecord === undefined || owner === undefined
+    ? true
+    : owner.prepareDispatch(mailboxRecord, signal);
+}
+
 function readyOwner(
   owner: string,
   nodeRid: string,
@@ -2536,93 +2727,16 @@ function encodeMultipartApplicationFrame(parts: MessageLike | readonly MessageLi
   );
 }
 
-function decodeApplicationEnvelope(frame: Uint8Array) {
-  const bytes = Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
-  if (
-    bytes.length < APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES ||
-    bytes[0] !== APPLICATION_PAYLOAD_VERSION
-  ) {
-    throw new ServiceWireProtocolError('Invalid application envelope.');
-  }
-  const bodyLength = bytes.readUInt32BE(1);
-  if (bodyLength !== bytes.length - 5) {
-    throw new ServiceWireProtocolError('Invalid application envelope length.');
-  }
-  let offset = 5;
-  const packetLength = bytes[offset++]!;
-  if (packetLength === 0 || bytes.length - offset < packetLength + 1) {
-    throw new ServiceWireProtocolError('Invalid application envelope packet name.');
-  }
-  let packetName: string;
-  try {
-    packetName = FATAL_UTF8.decode(bytes.subarray(offset, offset + packetLength));
-  } catch {
-    throw new ServiceWireProtocolError('Invalid application envelope packet name.');
-  }
-  offset += packetLength;
-  const contentLength = bytes[offset++]!;
-  if (contentLength === 0 || bytes.length - offset < contentLength + 4) {
-    throw new ServiceWireProtocolError('Invalid application envelope content type.');
-  }
-  let contentType: string;
-  try {
-    contentType = FATAL_UTF8.decode(bytes.subarray(offset, offset + contentLength));
-  } catch {
-    throw new ServiceWireProtocolError('Invalid application envelope content type.');
-  }
-  offset += contentLength;
-  const payloadLength = bytes.readUInt32BE(offset);
-  offset += 4;
-  if (
-    packetName !== MULTIPART_PACKET_NAME ||
-    contentType !== MULTIPART_CONTENT_TYPE ||
-    payloadLength !== bytes.length - offset
-  ) {
-    throw new ServiceWireProtocolError('Unexpected M6A application payload.');
-  }
-  return { packetName, contentType, payload: bytes.subarray(offset) };
+function decodeMultipart(payload: Uint8Array): FrameworkMessage[] {
+  return decodeMultipartParts(payload, ZLinkBufferMessage.fromOwned, closeMultipartMessage);
 }
 
-function decodeMultipart(payload: Uint8Array): FrameworkMessage[] {
-  const buffers = decodeMultipartBuffers(payload);
-  const parts = new Array<FrameworkMessage>(buffers.length);
-  let materialized = 0;
-  try {
-    for (; materialized < buffers.length; materialized += 1) {
-      parts[materialized] = ZLinkBufferMessage.fromOwned(buffers[materialized]!);
-    }
-    return parts;
-  } catch (error) {
-    for (let index = 0; index < materialized; index += 1) parts[index]!.close();
-    throw error;
-  }
+function closeMultipartMessage(part: FrameworkMessage): void {
+  part.close();
 }
 
-function decodeMultipartBuffers(payload: Uint8Array): Buffer[] {
-  const bytes = Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
-  if (bytes.length < 4) throw new ServiceWireProtocolError('Truncated multipart payload.');
-  const count = bytes.readUInt32BE(0);
-  if (count === 0 || count > Math.floor((bytes.length - 4) / 4)) {
-    throw new ServiceWireProtocolError('Invalid multipart part count.');
-  }
-  const result = new Array<Buffer>(count);
-  let offset = 4;
-  for (let index = 0; index < count; index++) {
-    if (bytes.length - offset < 4) {
-      throw new ServiceWireProtocolError('Truncated multipart part length.');
-    }
-    const length = bytes.readUInt32BE(offset);
-    offset += 4;
-    if (bytes.length - offset < length) {
-      throw new ServiceWireProtocolError('Truncated multipart part.');
-    }
-    result[index] = bytes.subarray(offset, offset + length);
-    offset += length;
-  }
-  if (offset !== bytes.length) {
-    throw new ServiceWireProtocolError('Multipart payload has trailing bytes.');
-  }
-  return result;
+function borrowMultipartPart(part: Buffer): Buffer {
+  return part;
 }
 
 function messageBytesView(value: MessageLike): Uint8Array {