@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,17 +1,14 @@
-import { randomBytes } from 'node:crypto';
-import { setImmediate as yieldToIO } from 'node:timers/promises';
 import {
   decodeStreamWireFrame,
   decodeStreamWireHeader,
   encodeStreamWireFrame,
   encodeStreamWireHeader
 } from '@zlink-systems/stream-wire';
-import { disconnectStreamPeer } from './node-socket-backend-adapter';
-import { ZLinkFrameworkException } from '../../../contracts';
-import { internalFrameworkWireReply } from '../../framework-errors-internal';
 import {
-  Message,
   RoutingId as BindingRoutingId,
+  ConfigError,
+  ConfigResult,
+  Message,
   RequestResult,
   SubmitError,
   SubmitResult,
@@ -19,51 +16,64 @@ import {
   type StreamSocket,
   type SubmitResult as SubmitResultValue
 } from '@zlink-systems/zlink';
-import {
-  isZLinkBackendResultError,
-  ZLinkBackendResultError,
-  type ZLinkBackendMessageLike as MessageLike
-} from '../runtime-values';
-import { ZLinkBufferMessage } from '../runtime-message';
+import { randomBytes } from 'node:crypto';
+import { setImmediate as yieldToIO } from 'node:timers/promises';
+import { type RoutingId, ZLinkFrameworkException } from '../../../contracts';
+
 import type { Message as FrameworkMessage } from '../../../contracts/Common/Message';
-import type { ZLinkDispatchErrorReporter } from '../../channels/dispatch-error-reporter';
-import type {
-  MeshOperationId,
-  MeshPeerEntry,
-  MeshPublisher,
-  ReadyBatch,
-  ReadyRecord,
-  ReceiveBatch,
-  ReceiveRecord,
-  ServiceSpot,
-  StreamSessionActorAuthorityFence,
-  StreamSessionService
-} from '../../foundation/service-runtime-contracts';
+import { ZLinkConfigurationException } from '../../../contracts/Configuration/ConfigurationException';
+import { buildAdvertisedEndpoint } from '../../../contracts/Configuration/EndpointNotation';
+import { DEFAULT_ACTIVATION_CONCURRENCY_LIMIT } from '../../../contracts/Configuration/InternalDefaults';
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../../contracts/Configuration/Registration';
 import {
-  OperationKind,
-  ReadyDomain,
-  ReadyOwnerKind,
-  ReceiveKind
-} from '../../foundation/service-runtime-contracts';
+  isValidPositiveCapacity,
+  isValidPublicWeight,
+  ZLINK_DEFAULT_PUBLIC_WEIGHT,
+  ZLINK_MAX_CAPACITY,
+  ZLINK_MAX_PUBLIC_WEIGHT
+} from '../../../contracts/Configuration/RegistrationBuilderPolicy';
+import { shouldCompactBackingArray } from '../../admission';
+import type { ApplicationJobQueuePort } from '../../application-jobs/contracts';
+import type { ZLinkDispatchErrorReporter } from '../../channels/dispatch-error-reporter';
+import { ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE } from '../../foundation/operation-identity';
 import {
   OperationCancelledError,
   OperationTimeoutError
 } from '../../foundation/operation-registry';
 import {
   RawServiceMeshRuntime,
+  RAW_MESH_RECEIVE_TIME_BUDGET_MS,
   type RawServiceRequestResult
 } from '../../foundation/raw-service-mesh-runtime';
+import type { ServiceInstanceActivationRecoveryEnvelope } from '../../foundation/service-instance-activation-recovery-codec';
+import type {
+  ServiceMailboxClaim,
+  ServiceMailboxDomain,
+  ServiceMailboxRecord
+} from '../../foundation/service-mailbox';
+import { encodeServiceMetadataFrame } from '../../foundation/service-metadata-codec';
 import {
-  decodeApplicationPayloadView,
-  encodeMultipartApplicationPayload,
-  type ServiceApplicationPayload,
-  ServiceWireProtocolError
-} from '../../foundation/service-wire-m6a-codec';
-import {
-  SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
-  SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
-  SERVICE_WIRE_REQUIRED_CAPABILITY
-} from '../../foundation/service-wire-constants.generated';
+  type MeshOperationId,
+  type MeshPeerEntry,
+  type MeshPublisher,
+  type ReadyBatch,
+  type ReadyRecord,
+  type ReceiveBatch,
+  type ReceiveRecord,
+  type ServiceSpot,
+  type StreamSessionActorAuthorityFence,
+  type StreamSessionService,
+  MeshNodeRuntimeState,
+  MeshPeerRuntimeState,
+  OperationKind,
+  ReadyDomain,
+  ReadyOwnerKind,
+  ReceiveKind,
+  StreamSessionRuntimeState
+} from '../../foundation/service-runtime-contracts';
+
+import { serviceSessionBindingIngressPortIfRegistered } from '../../foundation/service-session-binding-ingress-port';
+import type { ServiceActorRef, ServiceSpotState } from '../../foundation/service-stateful-registry';
 import {
   ServiceStatefulRuntime,
   statefulMailboxData,
@@ -71,14 +81,12 @@ import {
   type ServiceInstanceApplicationLifecycle,
   type ServicePendingInstanceActivation,
   type ServiceSpotMessageFollowSeal,
-  type ServiceUserSpotOperationHandler,
-  type ServiceUserSpotOperationResult,
   type ServiceStatefulMailboxData,
   type ServiceStatefulPendingOperation,
-  type ServiceStatefulResult
+  type ServiceStatefulResult,
+  type ServiceUserSpotOperationHandler,
+  type ServiceUserSpotOperationResult
 } from '../../foundation/service-stateful-runtime';
-import type { ServiceActorRef, ServiceSpotState } from '../../foundation/service-stateful-registry';
-import { serviceSessionBindingIngressPortIfRegistered } from '../../foundation/service-session-binding-ingress-port';
 import type {
   ServiceActorCreateRecord,
   ServiceDirectSpotRouteFence,
@@ -89,36 +97,55 @@ import type {
   ServiceUserSpotCloseRecord,
   ServiceUserSpotCreateRecord
 } from '../../foundation/service-stateful-wire-codec';
-import { encodeServiceMetadataFrame } from '../../foundation/service-metadata-codec';
-import type { ServiceInstanceActivationRecoveryEnvelope } from '../../foundation/service-instance-activation-recovery-codec';
-import type {
-  ServiceMailboxClaim,
-  ServiceMailboxDomain,
-  ServiceMailboxRecord
-} from '../../foundation/service-mailbox';
 import type {
   ServiceChannelDescriptor,
   ServiceNodeDescriptor
 } from '../../foundation/service-topology-registry';
-import type { RoutingId } from '../../../contracts';
-import { buildAdvertisedEndpoint } from '../../../contracts/Configuration/EndpointNotation';
-import { ZLinkConfigurationException } from '../../../contracts/Configuration/ConfigurationException';
+import { SERVICE_WIRE_COMMAND_OFFSET } from '../../foundation/service-wire-binary-primitives';
+import {
+  SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
+  SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
+  SERVICE_WIRE_REQUIRED_CAPABILITY,
+  ServiceWireCommand,
+  ServiceWireFrameworkErrorCode
+} from '../../foundation/service-wire-constants.generated';
+import {
+  APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES,
+  APPLICATION_PAYLOAD_VERSION,
+  decodeApplicationPayloadView,
+  encodeMultipartApplicationPayload,
+  ServiceWireProtocolError,
+  type ServiceApplicationPayload
+} from '../../foundation/service-wire-m6a-codec';
+import { submitToRequestResult } from '../../messaging/submission-result';
+import { internalFrameworkWireReply } from '../../framework-errors-internal';
 import type {
   ZLinkBackendActorRef,
-  ZLinkBackendActorSessionSendFence,
-  ZLinkBackendObjectPlacement,
-  ZLinkBackendMeshNode
+  ZLinkBackendMeshNode,
+  ZLinkBackendObjectPlacement
 } from '../contracts';
 import type { ZLinkRawBindingPort } from '../raw-binding-port';
-import type { ApplicationJobQueuePort } from '../../application-jobs/contracts';
+import { ZLinkBufferMessage } from '../runtime-message';
+import {
+  isZLinkBackendResultError,
+  ZLinkBackendResultError,
+  type ZLinkBackendMessageLike as MessageLike
+} from '../runtime-values';
+import { translateBindingResultError } from './node-backend-adapter-support';
+import { disconnectStreamPeer } 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 monitor/admission/liveness cadence. Only the binding
+// Preserve the existing route observation/admission/liveness cadence. Only the binding
 // readable handler admits receive work; this timer never probes the socket.
 const MESH_BACKEND_MAINTENANCE_INTERVAL_MS = 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;
 /**
  * Conservative Actor Join admission cap for relocation state chunks (spec 15
  * §4.2): a stable lower bound safe on any deployment, never lowered on
@@ -155,21 +182,32 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   private readyHandler?: (domains: number) => number;
   private maintenanceTimer?: NodeJS.Timeout;
   private pumping = false;
-  private readable = false;
-  private readonly onReadable = (): void => {
-    this.readable = true;
+  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();
   };
   private readonly onMaintenance = (): void => {
     this.maintenanceTimer = undefined;
+    if (this.closed) return;
+    const nowMs = performance.now();
+    const turnDeadlineMs = nowMs + RAW_MESH_RECEIVE_TIME_BUDGET_MS;
+    this.runtime?.expireOperations(
+      nowMs,
+      nowMs + RAW_MESH_RECEIVE_TIME_BUDGET_MS * MESH_BACKEND_RAW_MAINTENANCE_SHARE
+    );
+    this.stateful?.expireOperations(nowMs, turnDeadlineMs);
+    this.scheduleMaintenance();
     void this.pump();
   };
+  private readonly onPendingOperationsChanged = (): void => this.scheduleMaintenance();
   private nextPeerIntent = 1n;
   private closed = false;
   private objectRole: ServiceNodeDescriptor['objectRole'] = 'none';
-  private placementWeight = 100;
-  private activeCapacityLimit = 10_000;
-  private pendingCapacityLimit = 128;
+  private placementWeight = ZLINK_DEFAULT_PUBLIC_WEIGHT;
+  private activeCapacityLimit: number = DEFAULT_NATIVE_ACTIVE_CAPACITY;
+  private pendingCapacityLimit: number = DEFAULT_ACTIVATION_CONCURRENCY_LIMIT;
   private objectCapabilities: readonly string[] = [];
   private maintenanceWave?: string;
   private mailboxRecordDropped?: (record: {
@@ -349,6 +387,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       throw new Error('MeshNode bind endpoint is not configured.');
     const descriptor = this.createDescriptor();
     const runtime = new RawServiceMeshRuntime({
+      onPendingOperationsChanged: this.onPendingOperationsChanged,
       descriptor,
       resolveAdvertisedEndpoint: (boundEndpoint) => this.resolveAdvertisedEndpoint(boundEndpoint),
       bindingPort: this.bindingPort,
@@ -392,7 +431,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.stateful = new ServiceStatefulRuntime(
       runtime,
       descriptor.nodeRoutingId,
-      descriptor.lifecycleGeneration
+      descriptor.lifecycleGeneration,
+      this.onPendingOperationsChanged
     );
     if (this.dispatchErrors !== undefined) {
       this.stateful.setDispatchErrorReporter(this.dispatchErrors, this.meshName);
@@ -441,7 +481,6 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
 
   close(): void {
     if (this.closed) return;
-    this.closed = true;
     if (this.maintenanceTimer !== undefined) clearTimeout(this.maintenanceTimer);
     this.maintenanceTimer = undefined;
     this.stateful?.close();
@@ -449,6 +488,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.runtime?.close();
     this.runtime = undefined;
     this.clearCompletions();
+    this.closed = true;
   }
 
   addChannelName(name: string): void {
@@ -508,7 +548,6 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
             lifecycleGeneration: options.expectedLifecycleGeneration
           })
     });
-    if (nodeRoutingId !== undefined) await runtime.announcePeer(nodeRoutingId);
     return intent;
   }
 
@@ -644,7 +683,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return await this.requireRuntime().requestService(
       String(targetRid),
       frames.map((frame) => Buffer.from(frame)),
-      options?.timeoutMs ?? 30_000
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
     );
   }
 
@@ -656,7 +695,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     const pending = this.requireRuntime().requestToNode(
       String(targetRid),
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? 30_000
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
     );
     return this.observeCompletion(pending.id, OperationKind.NodeRequest, pending.promise);
   }
@@ -676,7 +715,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     const pending = this.requireRuntime().requestToChannel(
       channelName,
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? 30_000
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
     );
     return this.observeCompletion(pending.id, OperationKind.ChannelRequest, pending.promise);
   }
@@ -725,7 +764,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       source: 1,
       state:
         this.runtime?.isPeerRouteReady(peer.descriptor.nodeRoutingId) === false
-          ? 1
+          ? MeshPeerRuntimeState.Connecting
           : peerStateCode(peer.descriptor.state),
       routingId: peer.descriptor.nodeRoutingId as RoutingId,
       lifecycleGeneration: peer.descriptor.lifecycleGeneration,
@@ -739,7 +778,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       connectionIntentId:
         findIntent(descriptor.nodeRoutingId, descriptor.advertisedEndpoint)?.id ?? 0n,
       source: 1,
-      state: 6,
+      state: MeshPeerRuntimeState.NotRequired,
       routingId: descriptor.nodeRoutingId as RoutingId,
       lifecycleGeneration: descriptor.lifecycleGeneration,
       descriptorRevision: descriptor.descriptorRevision,
@@ -929,17 +968,19 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     stableType: string,
     generation: bigint,
     authorityOwnerGeneration: bigint,
-    spotId: string,
+    spotId: string | undefined,
     spotGeneration: bigint,
     membershipEpoch: bigint
   ): ZLinkBackendActorRef {
-    return this.requireStateful().restoreActorAuthority(
+    const stateful = this.requireStateful();
+    const entry = spotId === undefined ? stateful.entrySpot().ref : undefined;
+    return stateful.restoreActorAuthority(
       actorId,
       stableType,
       generation,
       authorityOwnerGeneration,
-      spotId,
-      spotGeneration,
+      entry?.spotId ?? spotId!,
+      entry?.generation ?? spotGeneration,
       membershipEpoch
     ).ref;
   }
@@ -1115,13 +1156,15 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     route: ServiceInstanceRouteFence,
     parts: MessageLike | readonly MessageLike[],
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    instanceIntent = false
   ): Promise<SubmitResult> {
     const result = await this.requireStateful().sendToInstanceSpot(
       route,
       encodeMultipart(parts),
       sourceSpotId,
-      metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata)
+      metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
+      instanceIntent
     );
     return result as SubmitResult;
   }
@@ -1129,9 +1172,10 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   requestInstanceSpot(
     route: ServiceInstanceRouteFence,
     parts: MessageLike | readonly MessageLike[],
-    timeoutMs = 30_000,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    instanceIntent = false
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.InstanceSpotRequest,
@@ -1140,7 +1184,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         encodeMultipart(parts),
         timeoutMs,
         sourceSpotId,
-        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata)
+        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
+        instanceIntent
       )
     );
   }
@@ -1148,7 +1193,9 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   actorLookup(actorId: string) {
     const actor = this.requireStateful().actor(actorId);
     if (actor === undefined) {
-      throw Object.assign(new Error(`Actor '${actorId}' was not found.`), { nativeErrno: 2 });
+      const error = new ConfigError(ConfigResult.NotFound);
+      error.message = `Actor '${actorId}' was not found.`;
+      throw error;
     }
     return {
       actor: actor.ref,
@@ -1158,14 +1205,21 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     };
   }
 
-  lookupRemoteActor(targetNodeRid: unknown, actorId: string, timeoutMs = 30_000): MeshOperationId {
+  lookupRemoteActor(
+    targetNodeRid: unknown,
+    actorId: string,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
+  ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorLookup,
       this.requireStateful().lookupRemoteActor(String(targetNodeRid), actorId, timeoutMs)
     );
   }
 
-  destroyActor(actor: ZLinkBackendActorRef, timeoutMs = 30_000): MeshOperationId {
+  destroyActor(
+    actor: ZLinkBackendActorRef,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
+  ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorDestroy,
       this.requireStateful().destroyActor(actor, timeoutMs)
@@ -1178,7 +1232,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     targetSpotId: unknown,
     targetSpotGeneration: bigint,
     request: ServiceApplicationPayload,
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorJoin,
@@ -1205,7 +1259,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       readonly ownerLeaseGeneration: bigint;
     },
     local: { readonly phase: 'admission'; readonly transferId: string },
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorJoin,
@@ -1226,7 +1280,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     actor: ZLinkBackendActorRef,
     targetNodeRid: unknown,
     request: ServiceApplicationPayload,
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     const target = String(targetNodeRid);
     return this.observeStateful(
@@ -1245,7 +1299,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       readonly ownerLeaseGeneration: bigint;
     },
     local: { readonly phase: 'admission'; readonly transferId: string },
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     const target = String(targetNodeRid);
     return this.observeStateful(
@@ -1285,7 +1339,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         this.peerGeneration(String(actor.nodeRid)),
         actor.generation,
         encodeMultipart(parts),
-        options?.timeoutMs ?? 30_000
+        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
       )
     );
   }
@@ -1317,7 +1371,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         this.peerGeneration(String(target.nodeRid)),
         target.generation,
         encodeMultipart(parts),
-        options?.timeoutMs ?? 30_000,
+        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
         source
       )
     );
@@ -1327,21 +1381,19 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     actor: ZLinkBackendActorRef,
     expectedBindingGeneration: bigint,
     parts: MessageLike | readonly MessageLike[],
-    _flags?: number,
-    actorFence?: ZLinkBackendActorSessionSendFence
+    _flags?: number
   ): Promise<SubmitResultValue> {
     return (await this.requireStateful().sendBoundSession(
       actor,
       expectedBindingGeneration,
-      encodeMultipart(parts),
-      actorFence
+      encodeMultipart(parts)
     )) as SubmitResultValue;
   }
 
   closeActorBoundSession(
     actor: ZLinkBackendActorRef,
     expectedBindingGeneration: bigint,
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     const binding = this.requireStateful().registry.binding(actor);
     if (binding === undefined) {
@@ -1361,7 +1413,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   leaveActor(
     actor: ZLinkBackendActorRef,
     expectedMembershipEpoch: bigint,
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorLeave,
@@ -1445,7 +1497,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       nodeRoutingId: this.routingId,
       lifecycleGeneration: this.lifecycleGeneration,
       descriptorRevision: 1n,
-      advertisedEndpoint: this.bindEndpoint ?? 'inproc://not-started',
+      advertisedEndpoint: this.bindEndpoint ?? UNSTARTED_DIAGNOSTIC_ENDPOINT,
       channels,
       state: 'preparing',
       // Plaintext RouteMesh peers use the shared default admission identity.
@@ -1473,27 +1525,33 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   }
 
   private scheduleMaintenance(): void {
-    if (this.closed || this.maintenanceTimer !== undefined) return;
-    this.maintenanceTimer = setTimeout(this.onMaintenance, MESH_BACKEND_MAINTENANCE_INTERVAL_MS);
+    if (this.closed) return;
+    this.maintenanceTimer ??= setTimeout(this.onMaintenance, MESH_BACKEND_MAINTENANCE_INTERVAL_MS);
+    const pending =
+      (this.runtime?.pendingOperationCount ?? 0) + (this.stateful?.pendingOperationCount ?? 0) > 0;
+    if (pending === this.maintenanceTimer.hasRef()) return;
+    if (pending) {
+      this.maintenanceTimer.ref();
+    } else {
+      this.maintenanceTimer.unref();
+    }
   }
 
   private async pump(): Promise<void> {
     if (this.isClosed() || this.pumping) return;
     this.pumping = true;
-    if (this.maintenanceTimer !== undefined) clearTimeout(this.maintenanceTimer);
-    this.maintenanceTimer = undefined;
     try {
       do {
-        const receiveReady = this.readable;
-        this.readable = false;
-        const more = await this.requireRuntime().pumpBatch(receiveReady);
+        const ready = this.readable;
+        this.readable = 0;
+        const more = await this.requireRuntime().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.
-          this.readable = true;
+          this.readable |= 1;
           await yieldToIO();
         }
-      } while (!this.closed && this.readable);
+      } while (!this.closed && this.readable !== 0);
     } finally {
       this.pumping = false;
       this.scheduleMaintenance();
@@ -1524,7 +1582,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     const id = { high: 1n, low };
     void promise.then(
       (result) => this.enqueueCompletion(id, operationKind, result),
-      (error) => this.enqueueCompletion(id, operationKind, genericOperationFailure(error))
+      (error) => this.enqueueCompletion(id, operationKind, requestFailureResult(error))
     );
     return id;
   }
@@ -1533,10 +1591,10 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     operationKind: number,
     pending: ServiceStatefulPendingOperation
   ): MeshOperationId {
-    const id = { high: 2n, low: pending.id };
+    const id = { high: ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE, low: pending.id };
     void pending.promise.then(
       (result) => this.enqueueCompletion(id, operationKind, result),
-      (error) => this.enqueueCompletion(id, operationKind, statefulOperationFailure(error))
+      (error) => this.enqueueCompletion(id, operationKind, requestFailureResult(error))
     );
     return id;
   }
@@ -1584,7 +1642,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.completionCount -= 1;
     if (this.completionCount === 0) {
       this.clearCompletions();
-    } else if (this.completionHead >= 1024 && this.completionHead * 2 >= this.completions.length) {
+    } else if (shouldCompactBackingArray(this.completionHead, this.completions.length)) {
       this.completions.splice(0, this.completionHead);
       this.completionHead = 0;
     }
@@ -1740,7 +1798,7 @@ class RawServiceSpot implements ServiceSpot {
       this.state,
       routeFence,
       parts,
-      options?.timeoutMs ?? 30_000
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
     );
   }
 
@@ -1816,7 +1874,7 @@ function entrySpotFenceVersion(generation: bigint): string {
 }
 
 class RawStreamSessionService implements StreamSessionService {
-  private state = 1;
+  private state: StreamSessionRuntimeState = StreamSessionRuntimeState.Created;
   private closed = false;
   private readonly sessionTargets = new Map<string, RoutingId>();
 
@@ -1831,7 +1889,7 @@ class RawStreamSessionService implements StreamSessionService {
 
   start(): void {
     if (this.closed) throw new Error('STREAM session service is closed.');
-    this.state = 2;
+    this.state = StreamSessionRuntimeState.Started;
   }
 
   shutdown(_timeoutMs: number): RequestResultValue {
@@ -1842,7 +1900,7 @@ class RawStreamSessionService implements StreamSessionService {
   close(): void {
     if (this.closed) return;
     this.closed = true;
-    this.state = 5;
+    this.state = StreamSessionRuntimeState.Closed;
     this.sessionTargets.clear();
   }
 
@@ -1859,7 +1917,11 @@ class RawStreamSessionService implements StreamSessionService {
     };
   }
 
-  lookupActor(targetNodeRid: RoutingId, actorId: string, timeoutMs = 30_000): MeshOperationId {
+  lookupActor(
+    targetNodeRid: RoutingId,
+    actorId: string,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
+  ): MeshOperationId {
     this.requireStarted();
     return this.observe(
       OperationKind.ActorLookup,
@@ -1870,7 +1932,7 @@ class RawStreamSessionService implements StreamSessionService {
   bindActor(
     sessionRid: RoutingId,
     actor: ServiceActorRef,
-    timeoutMs = 30_000,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     onBindingReplaced?: (
       actorId: string,
       retiredSession: ServiceRetiredBoundSessionRouteFence,
@@ -1890,7 +1952,6 @@ class RawStreamSessionService implements StreamSessionService {
         (targetSessionRid, payloadFrame) =>
           this.deliver(targetSessionRid, actor.actorId, payloadFrame),
         onBindingReplaced,
-        serviceSessionBindingIngressPortIfRegistered(this),
         actorAuthority
       )
     );
@@ -1900,7 +1961,7 @@ class RawStreamSessionService implements StreamSessionService {
     sessionRid: RoutingId,
     actor: ServiceActorRef,
     expectedBindingGeneration: bigint,
-    timeoutMs = 30_000
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS
   ): MeshOperationId {
     this.requireStarted();
     return this.observe(
@@ -1973,7 +2034,7 @@ class RawStreamSessionService implements StreamSessionService {
   }
 
   private requireStarted(): void {
-    if (this.state !== 2 || this.closed) {
+    if (this.state !== StreamSessionRuntimeState.Started || this.closed) {
       throw new Error('STREAM session service is not started.');
     }
   }
@@ -2215,7 +2276,7 @@ function decodeMultipartRecord(
     };
   }
   const header = record.parts[0]!;
-  const command = header[3]!;
+  const command = header[SERVICE_WIRE_COMMAND_OFFSET]!;
   const payloadFrame = record.parts[1]!;
   const application = decodeApplicationEnvelope(payloadFrame);
   const channelName = record.owner.startsWith('channel:')
@@ -2226,11 +2287,11 @@ function decodeMultipartRecord(
       ? { high: 0n, low: 0n }
       : { high: 1n, low: record.correlation };
   const kind =
-    command === 16
+    command === ServiceWireCommand.nodeSend
       ? ReceiveKind.NodeSend
-      : command === 17
+      : command === ServiceWireCommand.nodeRequest
         ? ReceiveKind.NodeRequest
-        : command === 18
+        : command === ServiceWireCommand.channelSend
           ? ReceiveKind.ChannelSend
           : ReceiveKind.ChannelRequest;
   const operationKind =
@@ -2287,7 +2348,7 @@ function decodeStatefulRecord(
   const operationId =
     record.correlation === undefined
       ? { high: 0n, low: 0n }
-      : { high: 2n, low: record.correlation };
+      : { high: ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE, low: record.correlation };
   const ingressLifecycle = receiveIngressLifecycle(record);
   return {
     kind: stateful.receiveKind,
@@ -2319,12 +2380,18 @@ function decodeStatefulRecord(
           : decodeMultipart(application.payload),
     ...(stateful.isPending === undefined ? {} : { isPending: stateful.isPending }),
     ...(stateful.deadlineUnixMs === undefined ? {} : { deadlineUnixMs: stateful.deadlineUnixMs }),
+    ...(stateful.activationRecord === undefined
+      ? {}
+      : { activationRecord: stateful.activationRecord }),
     ...(stateful.messageFollowOrigin === undefined
       ? {}
       : { messageFollowOrigin: stateful.messageFollowOrigin }),
     ...(stateful.onTerminalCompletion === undefined
       ? {}
       : { onTerminalCompletion: stateful.onTerminalCompletion }),
+    ...(stateful.onHandlerTurnStarted === undefined
+      ? {}
+      : { onHandlerTurnStarted: stateful.onHandlerTurnStarted }),
     reply(parts) {
       if (stateful.reply === undefined) return SubmitResult.InvalidState;
       return stateful.reply(RequestResult.Ok, 0, encodeMultipart(parts))
@@ -2430,38 +2497,45 @@ function readyDomain(domain: ServiceMailboxDomain): number {
 }
 
 /**
- * Classifies a generic node/channel request rejection into a completion
- * terminal. Spec 32-framework-error-model:91-92 — a reply that could not be
- * decoded (ServiceWireProtocolError from the reply parser) is a protocol
- * failure, not connection loss; only genuine transport rejections collapse to
- * NotConnected.
+ * The one classification of a failed node/channel/stateful request into its
+ * completion terminal. A binding REQUEST result is Core's decision and is kept
+ * as is; a submit failure is classified from its submission or completion phase.
+ * A reply that could not be decoded is a protocol
+ * failure (spec 32-framework-error-model:91-92). The failure code is a wire
+ * code, so a Core result carries 0.
  */
-export function genericOperationFailure(error: unknown): RawServiceRequestResult {
-  //  requestProtocolError(16): the schema terminal-failure-integrity rule
-  //  forbids a typed terminal (104) with failure none, so the synthesized
-  //  decode-failure pair is 104+16; genuine transport loss stays 109+0.
-  return error instanceof ServiceWireProtocolError
-    ? { terminalResult: RequestResult.ProtocolError, failureCode: 16 }
-    : { terminalResult: RequestResult.NotConnected, failureCode: 0 };
-}
-
-function statefulOperationFailure(error: unknown): RawServiceRequestResult {
-  if (error instanceof ZLinkFrameworkException) {
-    return internalFrameworkWireReply(error);
-  }
-  if (error instanceof OperationTimeoutError) {
-    return { terminalResult: RequestResult.TimedOut, failureCode: 0 };
+export function requestFailureResult(error: unknown): RawServiceRequestResult {
+  const failure = translateBindingResultError(error);
+  if (isZLinkBackendResultError(failure)) {
+    return {
+      terminalResult:
+        failure.operation === 'request'
+          ? failure.result
+          : submitToRequestResult(failure.result, failure.phase),
+      failureCode: 0
+    };
   }
-  if (isZLinkBackendResultError(error)) {
+  //  requestProtocolError(16): the schema terminal-failure-integrity rule
+  //  forbids a typed terminal (104) with failure none.
+  if (failure instanceof ServiceWireProtocolError) {
     return {
-      terminalResult: error.result,
-      failureCode: error.nativeErrno ?? 0
+      terminalResult: RequestResult.ProtocolError,
+      failureCode: ServiceWireFrameworkErrorCode.requestProtocolError
     };
   }
-  if (error instanceof OperationCancelledError) {
+  if (failure instanceof ZLinkFrameworkException) {
+    return internalFrameworkWireReply(failure);
+  }
+  if (failure instanceof OperationTimeoutError) {
+    return { terminalResult: RequestResult.TimedOut, failureCode: 0 };
+  }
+  if (failure instanceof OperationCancelledError) {
     return { terminalResult: RequestResult.NotConnected, failureCode: 0 };
   }
-  return { terminalResult: RequestResult.InternalError, failureCode: 17 };
+  return {
+    terminalResult: RequestResult.InternalError,
+    failureCode: ServiceWireFrameworkErrorCode.requestFailed
+  };
 }
 
 function encodeMultipart(parts: MessageLike | readonly MessageLike[]) {
@@ -2500,7 +2574,10 @@ function encodeMultipartApplicationFrame(parts: MessageLike | readonly MessageLi
 
 function decodeApplicationEnvelope(frame: Uint8Array) {
   const bytes = Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
-  if (bytes.length < 11 || bytes[0] !== 1) {
+  if (
+    bytes.length < APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES ||
+    bytes[0] !== APPLICATION_PAYLOAD_VERSION
+  ) {
     throw new ServiceWireProtocolError('Invalid application envelope.');
   }
   const bodyLength = bytes.readUInt32BE(1);
@@ -2598,22 +2675,35 @@ function requireRawReadyBatch(batch: ReadyBatch): RawReadyBatch {
   return batch;
 }
 
-function stateCode(state: ServiceNodeDescriptor['state']): number {
-  return ['preparing', 'serving', 'retiring', 'draining', 'stopped', 'error'].indexOf(state) + 1;
+function stateCode(state: ServiceNodeDescriptor['state']): MeshNodeRuntimeState {
+  switch (state) {
+    case 'preparing':
+      return MeshNodeRuntimeState.Preparing;
+    case 'serving':
+      return MeshNodeRuntimeState.Serving;
+    case 'retiring':
+      return MeshNodeRuntimeState.Retiring;
+    case 'draining':
+      return MeshNodeRuntimeState.Draining;
+    case 'stopped':
+      return MeshNodeRuntimeState.Stopped;
+    case 'error':
+      return MeshNodeRuntimeState.Error;
+  }
 }
 
 function peerStateCode(state: ServiceNodeDescriptor['state']): number {
   switch (state) {
     case 'preparing':
-      return 2;
+      return MeshPeerRuntimeState.Preparing;
     case 'serving':
     case 'retiring':
-      return 3;
+      return MeshPeerRuntimeState.Serving;
     case 'draining':
-      return 4;
+      return MeshPeerRuntimeState.Draining;
     case 'stopped':
     case 'error':
-      return 5;
+      return MeshPeerRuntimeState.Closed;
   }
 }
 
@@ -2626,15 +2716,15 @@ function createLifecycleGeneration(): bigint {
 }
 
 function requirePositivePlacementValue(value: number, name: string): number {
-  if (!Number.isSafeInteger(value) || value <= 0 || value > 0x7fff_ffff) {
-    throw new RangeError(`${name} must be an integer in 1..2147483647.`);
+  if (!isValidPositiveCapacity(value)) {
+    throw new RangeError(`${name} must be an integer in 1..${ZLINK_MAX_CAPACITY}.`);
   }
   return value;
 }
 
 function requirePublicWeight(value: number, name: string): number {
-  if (!Number.isInteger(value) || value < 0 || value > 10_000) {
-    throw new RangeError(`${name} must be an integer in 0..10000.`);
+  if (!isValidPublicWeight(value)) {
+    throw new RangeError(`${name} must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`);
   }
   return value;
 }