@zlink-systems/framework 0.26.0 → 0.27.0

package/src/runtime/activation-admission.ts

@@ -10,7 +10,6 @@ export interface ZLinkActivationConcurrency {
 }
 
 interface ZLinkActivationRecord {
-  readonly meshName: string;
   readonly limit: number;
   active: number;
 }
@@ -27,10 +26,7 @@ interface ZLinkActivationRecord {
 export class ZLinkActivationAdmission {
   private readonly records = new Map<string, ZLinkActivationRecord>();
 
-  constructor(
-    private readonly limitOf: (meshName: string) => number,
-    private readonly changed?: (meshName: string) => void
-  ) {}
+  constructor(private readonly limitOf: (meshName: string) => number) {}
 
   current(meshName: string): ZLinkActivationConcurrency {
     const record = this.records.get(meshName);
@@ -57,20 +53,18 @@ export class ZLinkActivationAdmission {
       );
     }
     record.active += 1;
-    this.changed?.(meshName);
     let released = false;
     return () => {
       if (released) return;
       released = true;
       record.active -= 1;
-      this.changed?.(meshName);
     };
   }
 
   private record(meshName: string): ZLinkActivationRecord {
     let record = this.records.get(meshName);
     if (record === undefined) {
-      record = { meshName, limit: this.limitOf(meshName), active: 0 };
+      record = { limit: this.limitOf(meshName), active: 0 };
       this.records.set(meshName, record);
     }
     return record;

package/src/runtime/actors/actor-authority-payload-codec.ts

@@ -1,13 +1,29 @@
-import type { RoutingId } from '../../contracts';
-import { ZLinkSpotKind, zlinkSpotKindFromWire, zlinkSpotKindToWire } from '../../contracts';
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
+import {
+  type RoutingId,
+  ZLinkSpotKind,
+  zlinkSpotKindFromWire,
+  zlinkSpotKindToWire
+} from '../../contracts';
+
+import { ZLINK_MAX_ROUTING_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { AUTHORITY_ENVELOPE_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 import { crc32c } from '../foundation/service-relocation-runtime';
+import { SERVICE_WIRE_TEXT8_MAX_BYTES } from '../foundation/service-wire-binary-primitives';
 import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
 
 const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_VERSION = 1;
 const AUTHORITY_FLAGS = 0;
 const ACTOR_RELOCATION_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x50]);
-const MAXIMUM_BYTES = 1024 * 1024;
+const AUTHORITY_MINIMUM_BYTES = 15;
+const ACTOR_RELOCATION_MINIMUM_BYTES = 32;
+const ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE = 5;
+const ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE = 6;
+const ACTOR_RELOCATION_FIRST_PHASE = 1;
+const ACTOR_RELOCATION_STEADY_PHASE = 4;
+const ENTRY_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.Entry);
+const USER_SPOT_WIRE_KIND = zlinkSpotKindToWire(ZLinkSpotKind.User);
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 
 export type ZLinkActorAuthorityState = 'creating' | 'ready';
@@ -47,8 +63,10 @@ export function encodeCanonicalAuthorityPayload(value: ZLinkCanonicalAuthorityPa
     body
   );
   const encoded = concat(envelope, u32be(crc32c(envelope)));
-  if (encoded.byteLength > MAXIMUM_BYTES) {
-    throw new RangeError('Actor authority payload exceeds 1 MiB.');
+  if (encoded.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new RangeError(
+      `Actor authority payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return encoded;
 }
@@ -59,7 +77,10 @@ export function decodeCanonicalAuthorityPayload(
 ): ZLinkCanonicalAuthorityPayload | undefined {
   try {
     const reader = new BigEndianReader(payload);
-    if (reader.bytes.byteLength < 15 || reader.bytes.byteLength > MAXIMUM_BYTES) {
+    if (
+      reader.bytes.byteLength < AUTHORITY_MINIMUM_BYTES ||
+      reader.bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES
+    ) {
       return undefined;
     }
     reader.expect(AUTHORITY_MAGIC);
@@ -81,7 +102,7 @@ export function decodeCanonicalAuthorityPayload(
 /** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.Encode. */
 export function encodeActorAuthorityPayload(value: ZLinkActorAuthorityPayload): Buffer {
   const spotKind = zlinkSpotKindToWire(value.currentSpotKind);
-  if (spotKind !== 1 && spotKind !== 2) {
+  if (spotKind !== ENTRY_SPOT_WIRE_KIND && spotKind !== USER_SPOT_WIRE_KIND) {
     throw new RangeError('Actor currentSpotKind must be Entry or User.');
   }
   const actor = concat(
@@ -173,7 +194,7 @@ export function actorRelocationAuthorityApplicationPayload(
   const current = decodeActorRelocationEnvelope(payload);
   return current === undefined
     ? Buffer.from(payload)
-    : current.phase === 4
+    : current.phase === ACTOR_RELOCATION_STEADY_PHASE
       ? Buffer.from(current.applicationPayload)
       : undefined;
 }
@@ -196,8 +217,10 @@ export function replaceActorRelocationAuthorityApplicationPayload(
     applicationPayload
   );
   const encoded = concat(withoutChecksum, u32le(crc32c(withoutChecksum)));
-  if (encoded.byteLength > MAXIMUM_BYTES) {
-    throw new RangeError('Actor relocation authority payload exceeds 1 MiB.');
+  if (encoded.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES) {
+    throw new RangeError(
+      `Actor relocation authority payload exceeds ${AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return encoded;
 }
@@ -205,7 +228,11 @@ export function replaceActorRelocationAuthorityApplicationPayload(
 function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnvelope | undefined {
   try {
     const bytes = Buffer.from(payload);
-    if (bytes.byteLength < 32 || bytes.byteLength > MAXIMUM_BYTES) return undefined;
+    if (
+      bytes.byteLength < ACTOR_RELOCATION_MINIMUM_BYTES ||
+      bytes.byteLength > AUTHORITY_ENVELOPE_MAX_BYTES
+    )
+      return undefined;
     const checksumOffset = bytes.byteLength - 4;
     if (bytes.readUInt32LE(checksumOffset) !== crc32c(bytes.subarray(0, checksumOffset))) {
       return undefined;
@@ -213,10 +240,15 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
     const reader = new LittleEndianReader(bytes.subarray(0, checksumOffset));
     reader.expect(ACTOR_RELOCATION_MAGIC);
     const version = reader.u16();
-    if (version !== 5 && version !== 6) return undefined;
+    if (
+      version !== ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE &&
+      version !== ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE
+    )
+      return undefined;
     if (reader.take(16).every((byte) => byte === 0)) return undefined;
     const phase = reader.u8();
-    if (phase < 1 || phase > 4) return undefined;
+    if (phase < ACTOR_RELOCATION_FIRST_PHASE || phase > ACTOR_RELOCATION_STEADY_PHASE)
+      return undefined;
     const isBound = reader.bool();
     if (isBound) {
       reader.bytes8();
@@ -230,7 +262,7 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
       const ownerLeaseGeneration = reader.u64();
       const sessionOwnerNodeGeneration = reader.u64();
       reader.u64();
-      if (version === 6) {
+      if (version === ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE) {
         reader.text16();
         reader.u64();
       }
@@ -247,7 +279,7 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
     }
     const prefix = Buffer.from(reader.bytes.subarray(0, reader.offset));
     const applicationLength = reader.i32();
-    if (applicationLength < 1 || applicationLength > MAXIMUM_BYTES) return undefined;
+    if (applicationLength < 1 || applicationLength > AUTHORITY_ENVELOPE_MAX_BYTES) return undefined;
     const applicationPayload = Buffer.from(reader.take(applicationLength));
     if (!reader.done) return undefined;
     return { prefix, phase, applicationPayload };
@@ -258,22 +290,28 @@ function decodeActorRelocationEnvelope(payload: Uint8Array): ActorRelocationEnve
 
 function text8(value: string, name: string): Buffer {
   const bytes = Buffer.from(value, 'utf8');
-  if (bytes.byteLength < 1 || bytes.byteLength > 0xff || bytes.includes(0)) {
-    throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+  if (
+    bytes.byteLength < 1 ||
+    bytes.byteLength > SERVICE_WIRE_TEXT8_MAX_BYTES ||
+    bytes.includes(0)
+  ) {
+    throw new RangeError(
+      `${name} must contain 1..${SERVICE_WIRE_TEXT8_MAX_BYTES} UTF-8 bytes without NUL.`
+    );
   }
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
 function rid(value: RoutingId, name: string): Buffer {
   const bytes = Buffer.from(encodeRoutingIdStorageHex(value), 'hex');
-  if (bytes.byteLength < 1 || bytes.byteLength > 0xff) {
-    throw new RangeError(`${name} must contain 1..255 bytes.`);
+  if (bytes.byteLength < 1 || bytes.byteLength > ZLINK_MAX_ROUTING_ID_BYTES) {
+    throw new RangeError(`${name} must contain 1..${ZLINK_MAX_ROUTING_ID_BYTES} bytes.`);
   }
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
 function nonzeroU64be(value: bigint, name: string): Buffer {
-  if (value === 0n || value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value === 0n || value < 0n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be a non-zero u64.`);
   }
   const result = Buffer.alloc(8);

package/src/runtime/actors/actor-client.ts

@@ -1,41 +1,57 @@
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
+  type ActorRef,
+  type RoutingId,
+  type ZLinkActorClient,
+  type ZLinkActorRequestCall,
+  type ZLinkActorSendCall,
+  type ZLinkMessageSerializer,
+  ZLinkFrameworkErrorKind,
+  ZLinkFrameworkException,
+  ZLinkSpotKind
+} from '../../contracts';
+
+import { ZLINK_MAX_ACTOR_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import type { Message } from '../../contracts/Common/Message';
+import { awaitWithAbort, throwIfAborted } from '../abort';
+import {
+  type ZLinkBackendActorRef,
+  type ZLinkBackendMeshNode,
+  type ZLinkMeshCompletionTable,
+  closeMeshCompletion
+} from '../backend';
+
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import {
+  isZLinkBackendResultError,
   RequestResult,
   SubmitResult,
-  isZLinkBackendResultError,
   ZLINK_BACKEND_SEND_NONE
 } from '../backend/runtime-values';
-import type {
-  ActorRef,
-  RoutingId,
-  ZLinkActorClient,
-  ZLinkActorRequestCall,
-  ZLinkActorSendCall,
-  ZLinkMessageSerializer
-} from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
-import { ZLinkFrameworkException, ZLinkFrameworkErrorKind } from '../../contracts';
+import { ZLinkConfigurationException } from '../configuration';
+import {
+  captureZLinkSpotSerialTurn,
+  currentZLinkSpotSerialSourceId,
+  requireZLinkYieldTurn,
+  type ZLinkSpotSerialTurn
+} from '../execution';
+import { remainingActorRequestTimeout, waitActorReply } from './actor-request-deadline';
 import {
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  internalFrameworkErrorKindFromWireFailureCode,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+import type { ZLinkResolvedActorRoute, ZLinkStoreLocationResolvers } from '../locations';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
+import { decodeFrameworkPayloadMessage, encodeFrameworkPayload } from '../messaging/payload-codec';
+import {
+  classifySubmitResult,
   requireOneWayCompletion,
   throwAlreadySubmitted,
   ZLinkSubmitStatus,
   type ZLinkSubmitResult
 } from '../messaging/submission-result';
-import type { Message } from '../../contracts/Common/Message';
-import type {
-  ZLinkBackendActorRef,
-  ZLinkBackendMeshNode,
-  ZLinkMeshCompletionTable
-} from '../backend';
-import { closeMeshCompletion } from '../backend';
-import { awaitWithAbort, throwIfAborted } from '../abort';
-import { encodeFrameworkPayload, decodeFrameworkPayloadMessage } from '../messaging/payload-codec';
-import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import {
   actorRequestDeadlineMetadata,
   decodeStreamHeader,
@@ -45,11 +61,7 @@ import {
   ZLinkStreamHeaderFlags,
   ZLinkStreamMessageKind
 } from '../streams/protocol';
-import type { ZLinkStoreLocationResolvers } from '../locations';
-import type { ZLinkResolvedActorRoute } from '../locations';
-import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
-import { encodeRemoteActorPacketRelayPayload } from './actor-packet-relay-wire';
-import { requestRoutedJsonReply } from './actor-routed-json-request';
+import { currentZLinkActorExecution } from './actor-execution-context';
 import {
   attachActorMessageFollowContext,
   createInitialActorMessageFollowContext,
@@ -57,13 +69,11 @@ import {
   type ZLinkActorMessageFollowContext
 } from './actor-message-follow-context';
 import {
-  captureZLinkSpotSerialTurn,
-  currentZLinkSpotSerialSourceId,
-  requireZLinkYieldTurn,
-  type ZLinkSpotSerialTurn
-} from '../execution';
-import { ZLinkConfigurationException } from '../configuration';
-import { currentZLinkActorExecution } from './actor-execution-context';
+  encodeRemoteActorPacketRelayPayload,
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
+} from './actor-packet-relay-wire';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+import { requestRoutedJsonReply } from './actor-routed-json-request';
 
 export interface ZLinkActorClientOptions {
   readonly nodeProvider: (meshName: string) => ZLinkBackendMeshNode | undefined;
@@ -163,7 +173,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
           if (duplicate !== undefined) submissions.push(duplicate);
         }
         await awaitWithAbort(Promise.all(submissions), signal);
-        return submitted();
+        return { status: ZLinkSubmitStatus.Submitted };
       }
       const node = this.requireNode(meshName);
       if (
@@ -181,9 +191,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
             returnResponse: false,
             messageFollowContext: messageFollow
           }),
-          { packetName: '__zlink.actor.packet.relay' }
+          { packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET }
         );
-        return submitted();
+        return { status: ZLinkSubmitStatus.Submitted };
       }
       return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
     } catch (error) {
@@ -214,7 +224,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       effectiveTimeoutMs === undefined ? undefined : performance.now() + effectiveTimeoutMs;
     const deadlineUnixMs =
       effectiveTimeoutMs === undefined ? undefined : Date.now() + effectiveTimeoutMs;
-    const route = await this.resolveActorRoute(actorId, signal);
+    const route = await this.resolveActorRoute(actorId, signal, deadlineMs);
     if (
       waitPolicy === 'async' &&
       sourceSpotId !== undefined &&
@@ -248,10 +258,13 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     );
     const routedActor = attachActorMessageFollowContext(actor, messageFollow);
     try {
+      const delivery = this.options
+        .transportDeliveryGate?.()
+        ?.waitBeforeSubmit(actorId, 'request', signal);
       const submissionCopies =
-        (await this.options
-          .transportDeliveryGate?.()
-          ?.waitBeforeSubmit(actorId, 'request', signal)) ?? 1;
+        delivery === undefined
+          ? 1
+          : ((await waitActorReply(delivery, actorId, deadlineMs, signal)) ?? 1);
       const handoff = this.options.handoffCapture?.(
         meshName,
         actor.actorId,
@@ -273,9 +286,11 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
           );
           if (duplicate !== undefined) submissions.push(duplicate);
         }
-        const replies = await waitHandoffReply<unknown[]>(
+        const replies = await waitActorReply<unknown[]>(
           Promise.all(submissions),
-          remainingActorRequestTimeout(actorId, deadlineMs)
+          actorId,
+          deadlineMs,
+          signal
         );
         return replies[0] as TReply;
       }
@@ -302,7 +317,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
 
   private async resolveActorRoute(
     actorId: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    deadlineMs?: number
   ): Promise<ZLinkResolvedActorRoute> {
     const resolver = this.options.locationResolver();
     if (resolver === undefined) {
@@ -311,7 +327,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         'Actor direct messaging requires a Location Store.'
       );
     }
-    const resolution = await resolver.resolveDirectActorRoute(actorId, signal);
+    const resolution = await resolver.resolveDirectActorRoute(actorId, signal, deadlineMs);
     if (resolution.kind === 'missing') {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
@@ -390,7 +406,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   ): Promise<ZLinkSubmitResult> {
     const node = this.requireNode(meshName);
     try {
-      return mapSubmitResult(
+      return classifySubmitResult(
         await node.sendToActor(actor, toMessageLikeParts(parts), {
           flags: ZLINK_BACKEND_SEND_NONE
         }),
@@ -398,11 +414,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       );
     } catch (error) {
       if (isZLinkBackendResultError(error)) {
-        return mapSubmitResult(error.result, 'Actor send');
+        return classifySubmitResult(error.result, 'Actor send', error.phase);
       }
-      throw isZLinkBackendResultError(error)
-        ? mapRequestError(error, 'Actor send')
-        : mapSubmitError(error, 'Actor send');
+      throw mapSubmitError(error, 'Actor send');
     }
   }
 
@@ -560,53 +574,12 @@ function remoteRelayErrorKind(value: unknown): ZLinkFrameworkInternalErrorKind {
     : ZLinkFrameworkInternalErrorKind.RequestFailed;
 }
 
-function remainingActorRequestTimeout(
-  actorId: string,
-  deadlineMs: number | undefined
-): number | undefined {
-  if (deadlineMs === undefined) return undefined;
-  const remaining = deadlineMs - performance.now();
-  if (remaining <= 0) {
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-      `Actor request '${actorId}' exceeded its deadline before submission.`
-    );
-  }
-  return Math.max(1, Math.ceil(remaining));
-}
-
 function requireActorId(actorId: string): void {
   const byteLength = Buffer.byteLength(actorId, 'utf8');
-  if (byteLength < 1 || byteLength > 255) {
-    throw new ZLinkConfigurationException('Actor ID must contain 1..255 UTF-8 bytes.');
-  }
-}
-
-async function waitHandoffReply<TReply>(
-  reply: Promise<unknown>,
-  timeoutMs: number | undefined
-): Promise<TReply> {
-  if (timeoutMs === undefined) return (await reply) as TReply;
-  let deadline: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      reply as Promise<TReply>,
-      new Promise<TReply>((_resolve, reject) => {
-        deadline = setTimeout(
-          () =>
-            reject(
-              createInternalFrameworkException(
-                ZLinkFrameworkInternalErrorKind.RequestFailed,
-                'Actor handoff request timed out.',
-                true
-              )
-            ),
-          timeoutMs
-        );
-      })
-    ]);
-  } finally {
-    if (deadline !== undefined) clearTimeout(deadline);
+  if (byteLength < 1 || byteLength > ZLINK_MAX_ACTOR_ID_BYTES) {
+    throw new ZLinkConfigurationException(
+      `Actor ID must contain 1..${ZLINK_MAX_ACTOR_ID_BYTES} UTF-8 bytes.`
+    );
   }
 }
 
@@ -861,7 +834,7 @@ function decodeActorReplyPayload<TReply>(
     payload,
     serializers,
     undefined,
-    'application/json',
+    ZlinkStreamContentType.Json,
     packetName,
     'reply'
   );
@@ -871,29 +844,6 @@ function mapSubmitError(error: unknown, operationName: string): Error {
   if (error instanceof ZLinkFrameworkException) {
     return error;
   }
-  if (isZLinkBackendResultError(error)) {
-    switch (error.result) {
-      case SubmitResult.NotConnected:
-        return routeNotConnected(
-          `${operationName} failed because the target route is not connected.`,
-          error
-        );
-      case SubmitResult.NotFound:
-        return createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
-          `${operationName} failed because the actor route was not found.`,
-          false,
-          error
-        );
-      default:
-        return createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestFailed,
-          `${operationName} failed with submit result ${error.result}.`,
-          false,
-          error
-        );
-    }
-  }
   return createInternalFrameworkException(
     ZLinkFrameworkInternalErrorKind.RouteNotConnected,
     `${operationName} failed before a reply was received.`,
@@ -902,79 +852,6 @@ function mapSubmitError(error: unknown, operationName: string): Error {
   );
 }
 
-function mapSubmitResult(result: number, operationName: string): ZLinkSubmitResult {
-  switch (result) {
-    case SubmitResult.Ok:
-      return submitted();
-    case SubmitResult.Backpressured:
-    case SubmitResult.NotAdmitted:
-      return { status: ZLinkSubmitStatus.Backpressured };
-    case SubmitResult.NotConnected:
-      return { status: ZLinkSubmitStatus.RouteNotConnected };
-    case SubmitResult.NotFound:
-      return { status: ZLinkSubmitStatus.TargetNotFound };
-    case SubmitResult.Terminated:
-      return { status: ZLinkSubmitStatus.Shutdown };
-    default:
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestFailed,
-        `${operationName} failed with submit result ${result}.`
-      );
-  }
-}
-
-function submitted(): ZLinkSubmitResult {
-  return { status: ZLinkSubmitStatus.Submitted };
-}
-
-//  Ownership-aware Actor remote-reply translator (spec 32:81-118, 99-103):
-//  the reply comes from a remote target, so a fine framework failure code
-//  refines the coarse terminal, and a terminal-only conflict/busy is the
-//  target's owner/queue state (retryable stale/Unavailable), never a
-//  source-owned queue exhaustion. Backpressure never appears on this reply
-//  path. Internal kinds are preserved so the stale-actor re-resolve retry
-//  (isStaleActorError) keeps working.
-function actorFailureCodeKind(failureErrno: number): ZLinkFrameworkInternalErrorKind | undefined {
-  switch (failureErrno) {
-    case 3:
-      return ZLinkFrameworkInternalErrorKind.ActorAlreadyExists;
-    case 4:
-      return ZLinkFrameworkInternalErrorKind.ActorTypeMismatch;
-    case 7:
-      return ZLinkFrameworkInternalErrorKind.SpotTypeMismatch;
-    case 8:
-      return ZLinkFrameworkInternalErrorKind.ActorSessionNotBound;
-    case 9:
-    case 14:
-      return ZLinkFrameworkInternalErrorKind.RequestTargetNotFound;
-    case 12:
-    case 16:
-      return ZLinkFrameworkInternalErrorKind.RequestProtocolError;
-    //  routeNotConnected(13) and a remote worker queue full(18) are Unavailable.
-    case 13:
-    case 18:
-      return ZLinkFrameworkInternalErrorKind.RouteNotConnected;
-    case 15:
-      return ZLinkFrameworkInternalErrorKind.RequestRejected;
-    case 19:
-      return ZLinkFrameworkInternalErrorKind.WorkerTimedOut;
-    case 17:
-      return ZLinkFrameworkInternalErrorKind.RequestFailed;
-    case 20:
-      return ZLinkFrameworkInternalErrorKind.WorkerFailed;
-    case 21:
-      return ZLinkFrameworkInternalErrorKind.ActorLocationStale;
-    case 33:
-      return ZLinkFrameworkInternalErrorKind.ActorGenerationStale;
-    case 34:
-      return ZLinkFrameworkInternalErrorKind.ActorMoving;
-    case 35:
-      return ZLinkFrameworkInternalErrorKind.RelocationDataLost;
-    default:
-      return undefined;
-  }
-}
-
 function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
   switch (result) {
     case RequestResult.TimedOut:
@@ -990,7 +867,7 @@ function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
     case RequestResult.NotConnected:
       return ZLinkFrameworkInternalErrorKind.RouteNotConnected;
     //  A terminal-only conflict/busy on a remote actor reply is the target's
-    //  stale/owner state: retryable ActorLocationStale (-> Unavailable).
+    //  stale/owner state: ActorLocationStale (Unavailable).
     case RequestResult.Conflict:
     case RequestResult.Busy:
       return ZLinkFrameworkInternalErrorKind.ActorLocationStale;
@@ -999,8 +876,11 @@ function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
   }
 }
 
+// The shared table preserves Actor fine kinds; without a recognized fine code,
+// the remote owner/queue terminal supplies the classification.
 function mapRequestResult(result: number, failureErrno: number, operationName: string): Error {
-  const kind = actorFailureCodeKind(failureErrno) ?? actorTerminalKind(result);
+  const kind =
+    internalFrameworkErrorKindFromWireFailureCode(failureErrno) ?? actorTerminalKind(result);
   return createInternalFrameworkException(
     kind,
     `${operationName} failed with request result ${result}` +
@@ -1008,13 +888,6 @@ function mapRequestResult(result: number, failureErrno: number, operationName: s
   );
 }
 
-function mapRequestError(
-  error: { readonly result: number; readonly failureErrno?: number },
-  operationName: string
-): Error {
-  return mapRequestResult(error.result, error.failureErrno ?? 0, operationName);
-}
-
 function routeNotConnected(message: string, cause?: unknown): ZLinkFrameworkException {
   return createInternalFrameworkException(
     ZLinkFrameworkInternalErrorKind.RouteNotConnected,