@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,92 @@
+import {
+  ZLinkSerialExecutionQueue,
+  type ZLinkSerialSchedulerOptions,
+  type ZLinkSerialWorkPreparation,
+  type ZLinkSerialWorkOptions,
+  type ZLinkSerialWorkRecord
+} from '../execution/serial-execution-queue';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import { runZLinkActorExecution } from './actor-execution-context';
+import {
+  bindApplicationJobPermit,
+  hasApplicationJobPermit
+} from '../application-jobs/application-job-queue-scope';
+
+export class ZLinkActorSerialExecutor {
+  private readonly scheduler: ZLinkSerialExecutionQueue;
+
+  constructor(
+    private readonly actorId: string,
+    private readonly sourceSpotId: unknown,
+    options?: ZLinkSerialSchedulerOptions
+  ) {
+    this.scheduler = new ZLinkSerialExecutionQueue(
+      (record) => this.runRecord(record),
+      {
+        ...options,
+        capacityError: options?.capacityError ?? (() =>
+          createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.WorkerQueueFull,
+            'Actor execution queue capacity was exceeded.'
+          ))
+      }
+    );
+  }
+
+  execute<T>(
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    const boundOperation = bindApplicationJobPermit(() =>
+      runZLinkActorExecution(this.actorId, this.sourceSpotId, operation));
+    return hasApplicationJobPermit()
+      ? this.scheduler.submitPreAdmitted(boundOperation, workOptions)
+      : this.scheduler.submit(boundOperation, workOptions);
+  }
+
+  /**
+   * Restores one non-executing durable prefix at the current Actor FIFO tail.
+   * Child callbacks enter Actor execution independently after the prefix
+   * reaches the head; the prefix itself never owns an application permit.
+   *
+   * @internal
+   */
+  admitDurablePrefix(
+    records: readonly {
+      readonly operation: (
+        executeChild: <TChild>(
+          child: () => Promise<TChild> | TChild
+        ) => Promise<TChild>
+      ) => Promise<void>;
+      readonly preparation?: ZLinkSerialWorkPreparation;
+      readonly workOptions?: ZLinkSerialWorkOptions;
+    }[]
+  ): readonly Promise<void>[] {
+    // No await occurs in this map: the whole durable prefix is appended in
+    // one event-loop turn before later ingress can observe the released hold.
+    return records.map(record => this.scheduler.admitDurablePrefix(
+      () => record.operation(child =>
+        runZLinkActorExecution(this.actorId, this.sourceSpotId, child)),
+      record.workOptions,
+      undefined,
+      record.preparation
+    ));
+  }
+
+  close(): Promise<void> {
+    return this.scheduler.close();
+  }
+
+  private async runRecord(record: ZLinkSerialWorkRecord<unknown>): Promise<void> {
+    try {
+      record.resolve(await record.operation());
+    } catch (error) {
+      record.reject(error);
+    } finally {
+      record.release();
+    }
+  }
+}

package/src/runtime/actors/actor-message-follow-context.ts

@@ -0,0 +1,347 @@
+import { createHash, randomBytes } from 'node:crypto';
+import type { ActorRef } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkResolvedActorRoute } from '../locations';
+import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
+
+export const ZLINK_MESSAGE_FOLLOW_MAX_HOPS = 8;
+
+export interface ZLinkActorMessageFollowOwnerFence {
+  readonly ownerId: string;
+  readonly ownerLeaseGeneration: string;
+  readonly nodeRid: string;
+  /** Canonical opaque RoutingId bytes. Older wire contexts may omit this field. */
+  readonly nodeRidHex?: string;
+  readonly nodeGeneration: string;
+  readonly authorityOwnerGeneration: string;
+}
+
+export interface ZLinkActorMessageFollowContext {
+  readonly operationId: string;
+  readonly objectGeneration: string;
+  readonly sourceOwner: ZLinkActorMessageFollowOwnerFence;
+  readonly targetOwner: ZLinkActorMessageFollowOwnerFence;
+  readonly deadlineUnixMs?: number;
+  readonly correlationId?: string;
+  readonly replyRouteId?: string;
+  readonly request: boolean;
+  readonly hopCount: number;
+  readonly visitedOwners: readonly string[];
+  readonly payloadChecksumSha256: string;
+}
+
+type ActorRefWithMessageFollow = ActorRef & {
+  readonly __zlinkMessageFollowContext?: ZLinkActorMessageFollowContext;
+};
+
+export function createMessageFollowId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+export function createInitialActorMessageFollowContext(
+  route: ZLinkResolvedActorRoute,
+  parts: readonly Message[],
+  request: boolean,
+  deadlineUnixMs?: number,
+  correlationId?: string,
+  operationId = createMessageFollowId(),
+  replyRouteId = request ? createMessageFollowId() : undefined
+): ZLinkActorMessageFollowContext {
+  const owner = ownerFence({
+    ownerId: route.ownerId,
+    ownerLeaseGeneration: route.ownerLeaseGeneration,
+    nodeRid: String(route.actorRef.nodeRid),
+    nodeRidHex: encodeRoutingIdStorageHex(route.actorRef.nodeRid),
+    nodeGeneration: route.ownerNodeGeneration,
+    authorityOwnerGeneration: route.authorityOwnerGeneration
+  });
+  return freezeContext({
+    operationId,
+    objectGeneration: route.actorRef.objectGeneration.toString(),
+    sourceOwner: owner,
+    targetOwner: owner,
+    deadlineUnixMs,
+    correlationId,
+    replyRouteId,
+    request,
+    hopCount: 0,
+    visitedOwners: [messageFollowOwnerFenceKey(owner)],
+    payloadChecksumSha256: actorMessageFollowPayloadChecksum(parts)
+  });
+}
+
+export function decodeActorMessageFollowContext(
+  value: unknown
+): ZLinkActorMessageFollowContext | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'object' || value === null) {
+    throw invalidContext('context must be an object');
+  }
+  const input = value as Record<string, unknown>;
+  const operationId = requireId(input.operationId, 'operationId');
+  const objectGeneration = requirePositiveBigInt(input.objectGeneration, 'objectGeneration');
+  const sourceOwner = decodeOwnerFence(input.sourceOwner, 'sourceOwner');
+  const targetOwner = decodeOwnerFence(input.targetOwner, 'targetOwner');
+  const request = input.request;
+  const hopCount = input.hopCount;
+  const checksum = input.payloadChecksumSha256;
+  if (typeof request !== 'boolean') throw invalidContext('request must be boolean');
+  if (!Number.isSafeInteger(hopCount) || (hopCount as number) < 0
+      || (hopCount as number) > ZLINK_MESSAGE_FOLLOW_MAX_HOPS) {
+    throw invalidContext('hopCount is outside 0..8');
+  }
+  if (typeof checksum !== 'string' || !/^[0-9a-f]{64}$/.test(checksum)) {
+    throw invalidContext('payload checksum is invalid');
+  }
+  const deadlineUnixMs = optionalPositiveSafeInteger(input.deadlineUnixMs, 'deadlineUnixMs');
+  const correlationId = optionalId(input.correlationId, 'correlationId');
+  const replyRouteId = optionalId(input.replyRouteId, 'replyRouteId');
+  if (request && (correlationId === undefined || replyRouteId === undefined)) {
+    throw invalidContext('request context requires correlationId and replyRouteId');
+  }
+  if (!request && replyRouteId !== undefined) {
+    throw invalidContext('one-way context must not contain replyRouteId');
+  }
+  if (!Array.isArray(input.visitedOwners)
+      || input.visitedOwners.some(item => typeof item !== 'string' || item.length === 0)
+      || input.visitedOwners.length !== (hopCount as number) + 1) {
+    throw invalidContext('visitedOwners does not match hopCount');
+  }
+  const visitedOwners = [...input.visitedOwners] as string[];
+  const targetOwnerKeys = messageFollowOwnerFenceCompatibleKeys(targetOwner);
+  if (new Set(visitedOwners).size !== visitedOwners.length
+      || !targetOwnerKeys.includes(visitedOwners[visitedOwners.length - 1])
+      || visitedOwners.slice(0, -1).some(key => targetOwnerKeys.includes(key))) {
+    throw invalidContext('visited owner fence chain is invalid');
+  }
+  return freezeContext({
+    operationId,
+    objectGeneration,
+    sourceOwner,
+    targetOwner,
+    deadlineUnixMs,
+    correlationId,
+    replyRouteId,
+    request,
+    hopCount: hopCount as number,
+    visitedOwners,
+    payloadChecksumSha256: checksum
+  });
+}
+
+export function advanceActorMessageFollowContext(
+  context: ZLinkActorMessageFollowContext,
+  sourceOwner: ZLinkActorMessageFollowOwnerFence,
+  targetOwner: ZLinkActorMessageFollowOwnerFence
+): ZLinkActorMessageFollowContext {
+  if (!messageFollowOwnerFencesEqual(context.targetOwner, sourceOwner)) {
+    throw invalidContext('source owner fence does not match the routed owner');
+  }
+  if (context.hopCount >= ZLINK_MESSAGE_FOLLOW_MAX_HOPS) {
+    throw invalidContext('Message Follow reached the 8-hop limit');
+  }
+  const targetKey = messageFollowOwnerFenceKey(targetOwner);
+  if (messageFollowOwnerFenceCompatibleKeys(targetOwner)
+    .some(key => context.visitedOwners.includes(key))) {
+    throw invalidContext('Message Follow owner loop was detected');
+  }
+  return freezeContext({
+    ...context,
+    sourceOwner,
+    targetOwner,
+    hopCount: context.hopCount + 1,
+    visitedOwners: [...context.visitedOwners, targetKey]
+  });
+}
+
+export function attachActorMessageFollowContext(
+  actorRef: ActorRef,
+  context: ZLinkActorMessageFollowContext
+): ActorRef {
+  return Object.freeze({
+    ...actorRef,
+    __zlinkMessageFollowContext: context
+  }) as ActorRef;
+}
+
+export function actorMessageFollowContext(
+  actorRef: ActorRef | undefined
+): ZLinkActorMessageFollowContext | undefined {
+  return (actorRef as ActorRefWithMessageFollow | undefined)
+    ?.__zlinkMessageFollowContext;
+}
+
+export function actorMessageFollowPayloadChecksum(parts: readonly Message[]): string {
+  const hash = createHash('sha256');
+  for (const part of parts) {
+    const bytes = Buffer.from(part.data());
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(bytes.length);
+    hash.update(length);
+    hash.update(bytes);
+  }
+  return hash.digest('hex');
+}
+
+export function verifyActorMessageFollowPayload(
+  context: ZLinkActorMessageFollowContext,
+  parts: readonly Message[]
+): void {
+  if (actorMessageFollowPayloadChecksum(parts) !== context.payloadChecksumSha256) {
+    throw invalidContext('payload checksum does not match');
+  }
+}
+
+export function messageFollowOwnerFenceKey(
+  fence: ZLinkActorMessageFollowOwnerFence
+): string {
+  return JSON.stringify([
+    'zlink-actor-message-follow-owner-fence',
+    2,
+    fence.nodeRidHex ?? encodeRoutingIdStorageHex(fence.nodeRid),
+    fence.nodeGeneration,
+    fence.ownerId,
+    fence.ownerLeaseGeneration,
+    fence.authorityOwnerGeneration
+  ]);
+}
+
+export function messageFollowOwnerFencesEqual(
+  left: ZLinkActorMessageFollowOwnerFence,
+  right: ZLinkActorMessageFollowOwnerFence
+): boolean {
+  return messageFollowOwnerFenceKey(left) === messageFollowOwnerFenceKey(right);
+}
+
+export function messageFollowOwnerNodeRid(
+  fence: ZLinkActorMessageFollowOwnerFence
+): ReturnType<typeof decodeRoutingId> {
+  return decodeRoutingId(fence.nodeRid, fence.nodeRidHex);
+}
+
+export function ownerFence(input: {
+  readonly ownerId: string;
+  readonly ownerLeaseGeneration: bigint | string;
+  readonly nodeRid: string;
+  readonly nodeRidHex?: string;
+  readonly nodeGeneration: bigint | string;
+  readonly authorityOwnerGeneration: bigint | string;
+}): ZLinkActorMessageFollowOwnerFence {
+  const nodeRidHex = optionalNodeRidHex(input.nodeRidHex, 'nodeRidHex');
+  const value = {
+    ownerId: requireText(input.ownerId, 'ownerId'),
+    ownerLeaseGeneration: requirePositiveBigInt(
+      String(input.ownerLeaseGeneration),
+      'ownerLeaseGeneration'
+    ),
+    nodeRid: requireText(input.nodeRid, 'nodeRid'),
+    ...(nodeRidHex === undefined ? {} : { nodeRidHex }),
+    nodeGeneration: requirePositiveBigInt(String(input.nodeGeneration), 'nodeGeneration'),
+    authorityOwnerGeneration: requirePositiveBigInt(
+      String(input.authorityOwnerGeneration),
+      'authorityOwnerGeneration'
+    )
+  };
+  return Object.freeze(value);
+}
+
+function decodeOwnerFence(
+  value: unknown,
+  name: string
+): ZLinkActorMessageFollowOwnerFence {
+  if (typeof value !== 'object' || value === null) {
+    throw invalidContext(`${name} must be an object`);
+  }
+  const input = value as Record<string, unknown>;
+  return ownerFence({
+    ownerId: requireText(input.ownerId, `${name}.ownerId`),
+    ownerLeaseGeneration: requirePositiveBigInt(
+      input.ownerLeaseGeneration,
+      `${name}.ownerLeaseGeneration`
+    ),
+    nodeRid: requireText(input.nodeRid, `${name}.nodeRid`),
+    nodeRidHex: optionalNodeRidHex(input.nodeRidHex, `${name}.nodeRidHex`),
+    nodeGeneration: requirePositiveBigInt(input.nodeGeneration, `${name}.nodeGeneration`),
+    authorityOwnerGeneration: requirePositiveBigInt(
+      input.authorityOwnerGeneration,
+      `${name}.authorityOwnerGeneration`
+    )
+  });
+}
+
+function freezeContext(
+  context: ZLinkActorMessageFollowContext
+): ZLinkActorMessageFollowContext {
+  return Object.freeze({
+    ...context,
+    sourceOwner: Object.freeze({ ...context.sourceOwner }),
+    targetOwner: Object.freeze({ ...context.targetOwner }),
+    visitedOwners: Object.freeze([...context.visitedOwners])
+  });
+}
+
+function requireId(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !/^[0-9a-f]{32}$/.test(value)
+      || /^0+$/.test(value)) {
+    throw invalidContext(`${name} must be a nonzero 128-bit lowercase hex value`);
+  }
+  return value;
+}
+
+function optionalId(value: unknown, name: string): string | undefined {
+  return value === undefined ? undefined : requireId(value, name);
+}
+
+function requireText(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw invalidContext(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requirePositiveBigInt(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !/^[1-9][0-9]*$/.test(value)) {
+    throw invalidContext(`${name} must be a positive decimal integer`);
+  }
+  return value;
+}
+
+function optionalNodeRidHex(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || value.length === 0 || value.length % 2 !== 0
+      || !/^[0-9a-f]+$/.test(value)) {
+    throw invalidContext(`${name} must be non-empty lowercase hexadecimal bytes`);
+  }
+  return value;
+}
+
+function messageFollowOwnerFenceCompatibleKeys(
+  fence: ZLinkActorMessageFollowOwnerFence
+): readonly string[] {
+  const canonical = messageFollowOwnerFenceKey(fence);
+  const textHex = encodeRoutingIdStorageHex(fence.nodeRid);
+  if (fence.nodeRid.includes('\u0000')
+      || fence.ownerId.includes('\u0000')
+      || (fence.nodeRidHex !== undefined && fence.nodeRidHex !== textHex)) {
+    return [canonical];
+  }
+  return [canonical, [
+    fence.nodeRid,
+    fence.nodeGeneration,
+    fence.ownerId,
+    fence.ownerLeaseGeneration,
+    fence.authorityOwnerGeneration
+  ].join('\u0000')];
+}
+
+function optionalPositiveSafeInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) {
+    throw invalidContext(`${name} must be a positive safe integer`);
+  }
+  return value as number;
+}
+
+function invalidContext(reason: string): Error {
+  return new Error(`Actor Message Follow context is invalid: ${reason}.`);
+}

package/src/runtime/actors/actor-native-lookup.ts

@@ -0,0 +1,38 @@
+import type {
+  ZLinkBackendActorRef,
+  ZLinkBackendMeshNode,
+  ZLinkBackendSpotNode
+} from '../backend/contracts';
+
+type ZLinkActorLookupNode = ZLinkBackendMeshNode | ZLinkBackendSpotNode;
+
+export function lookupNativeActorRef(
+  node: ZLinkActorLookupNode,
+  actorId: string
+): ZLinkBackendActorRef | undefined {
+  try {
+    const location = node.actorLookup(actorId);
+    if (location === undefined) {
+      return undefined;
+    }
+    const actor = 'actor' in location ? location.actor : location;
+    return {
+      nodeRid: actor.nodeRid as ZLinkBackendActorRef['nodeRid'],
+      actorId: actor.actorId,
+      generation: actor.generation
+    };
+  } catch (error) {
+    if (nativeErrno(error) === 2) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function nativeErrno(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
+    return undefined;
+  }
+  const value = error.nativeErrno;
+  return typeof value === 'number' ? value : undefined;
+}

package/src/runtime/actors/actor-packet-relay-wire.ts

@@ -0,0 +1,223 @@
+import type { ActorRef, RoutingId } from '../../contracts';
+import { ZLinkSpotKind } from '../../contracts';
+import { decodeRoutingId, routingIdWireHex } from '../routing-id';
+import type { ZLinkRemoteActorPacketTarget } from './actor-runtime-state';
+import {
+  decodeActorMessageFollowContext,
+  type ZLinkActorMessageFollowContext
+} from './actor-message-follow-context';
+
+export const ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = '__zlink.actor.packet.relay';
+export const ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = 'zlink.framework.actor.session_disconnected';
+export const ZLINK_REMOTE_ACTOR_SESSION_BIND_PACKET = 'framework.internal.actor-session-bind';
+
+export function encodeRemoteActorSessionBinding(input: {
+  readonly sessionNodeRid: RoutingId;
+  readonly sessionRid: RoutingId;
+}): Uint8Array {
+  return Buffer.from(JSON.stringify({
+    sessionNodeRid: String(input.sessionNodeRid),
+    sessionNodeRidHex: routingIdWireHex(input.sessionNodeRid),
+    sessionRid: String(input.sessionRid),
+    sessionRidHex: routingIdWireHex(input.sessionRid)
+  }));
+}
+
+export function decodeRemoteActorSessionBinding(payload: Uint8Array): {
+  readonly sessionNodeRid: RoutingId;
+  readonly sessionRid: RoutingId;
+} {
+  const decoded = JSON.parse(Buffer.from(payload).toString('utf8')) as Record<string, unknown>;
+  if (typeof decoded.sessionNodeRid !== 'string' || typeof decoded.sessionRid !== 'string') {
+    throw new Error('Remote actor session binding payload is invalid.');
+  }
+  return {
+    sessionNodeRid: decodeRoutingId(decoded.sessionNodeRid, decoded.sessionNodeRidHex),
+    sessionRid: decodeRoutingId(decoded.sessionRid, decoded.sessionRidHex)
+  };
+}
+
+export function encodeRemoteActorPacketRelayPayload(input: {
+  readonly actorId: string;
+  readonly routerChannelId?: string;
+  readonly boundSessionTargetNodeRid?: string;
+  readonly boundSessionSpotId?: string;
+  readonly header: Uint8Array;
+  readonly payload: Uint8Array;
+  readonly bindingActorRef?: ActorRef;
+  /** The actor reference used to preserve relocation context at the target Spot. */
+  readonly actorRef?: ActorRef;
+  readonly returnResponse?: boolean;
+  readonly messageFollowContext?: ZLinkActorMessageFollowContext;
+}): Record<string, unknown> {
+  return {
+    packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+    actorId: input.actorId,
+    routerChannelId: input.routerChannelId,
+    boundSessionTargetNodeRid: input.boundSessionTargetNodeRid,
+    boundSessionSpotId: input.boundSessionSpotId,
+    actorNodeRid: input.actorRef === undefined ? undefined : String(input.actorRef.nodeRid),
+    actorNodeRidHex: input.actorRef === undefined
+      ? undefined
+      : routingIdWireHex(input.actorRef.nodeRid),
+    actorGeneration: input.actorRef?.objectGeneration.toString(),
+    bindingActorNodeRid: input.bindingActorRef === undefined ? undefined : String(input.bindingActorRef.nodeRid),
+    bindingActorNodeRidHex: input.bindingActorRef === undefined
+      ? undefined
+      : routingIdWireHex(input.bindingActorRef.nodeRid),
+    bindingActorGeneration: input.bindingActorRef?.objectGeneration.toString(),
+    bindingGeneration: (input.bindingActorRef as (ActorRef & {
+      readonly bindingGeneration?: bigint;
+    }) | undefined)?.bindingGeneration?.toString(),
+    returnResponse: input.returnResponse,
+    messageFollowContext: input.messageFollowContext,
+    header: Buffer.from(input.header).toString('base64'),
+    payload: Buffer.from(input.payload).toString('base64')
+  };
+}
+
+export function encodeMessageFollowRemoteActorPacketRelayPayload(input: {
+  readonly actorId: string;
+  readonly routerChannelId?: string;
+  readonly boundSessionTargetNodeRid?: string;
+  readonly boundSessionSpotId?: string;
+  readonly header: string;
+  readonly payload: string;
+  readonly actorNodeRid: string;
+  readonly actorNodeRidHex?: string;
+  readonly actorGeneration: string;
+  readonly returnResponse: boolean;
+  readonly messageFollowContext: ZLinkActorMessageFollowContext;
+}): Record<string, unknown> {
+  return { packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, ...input };
+}
+
+export interface ZLinkRemoteActorPacketTargetWire {
+  readonly routerChannelId: string;
+  readonly targetNodeRid: string;
+  readonly targetNodeRidHex?: string;
+  readonly spotId: string;
+  readonly spotKind: ZLinkSpotKind;
+  readonly targetSpotGeneration?: string;
+  readonly targetNodeGeneration?: string;
+  readonly authorityOwnerGeneration?: string;
+  readonly targetOwnerId?: string;
+  readonly ownerLeaseGeneration?: string;
+  readonly authorityStoreVersion?: string;
+}
+
+export function encodeRemoteActorPacketTarget(
+  target: ZLinkRemoteActorPacketTarget | undefined
+): ZLinkRemoteActorPacketTargetWire | undefined {
+  if (target === undefined) {
+    return undefined;
+  }
+  return {
+    routerChannelId: target.routerChannelId,
+    targetNodeRid: String(target.targetNodeRid),
+    targetNodeRidHex: routingIdWireHex(target.targetNodeRid),
+    spotId: String(target.spotId),
+    spotKind: target.spotKind ?? ZLinkSpotKind.User,
+    targetSpotGeneration: target.targetSpotGeneration?.toString(),
+    targetNodeGeneration: target.targetNodeGeneration?.toString(),
+    authorityOwnerGeneration: target.authorityOwnerGeneration?.toString(),
+    targetOwnerId: target.targetOwnerId,
+    ownerLeaseGeneration: target.ownerLeaseGeneration?.toString(),
+    authorityStoreVersion: target.authorityStoreVersion
+  };
+}
+
+export function decodeRemoteActorPacketTarget(value: unknown): ZLinkRemoteActorPacketTarget | undefined {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    typeof (value as { routerChannelId?: unknown }).routerChannelId !== 'string' ||
+    typeof (value as { targetNodeRid?: unknown }).targetNodeRid !== 'string' ||
+    typeof (value as { spotId?: unknown }).spotId !== 'string'
+  ) {
+    return undefined;
+  }
+  return {
+    routerChannelId: (value as { routerChannelId: string }).routerChannelId,
+    targetNodeRid: decodeRoutingId(
+      (value as { targetNodeRid: string }).targetNodeRid,
+      (value as { targetNodeRidHex?: unknown }).targetNodeRidHex
+    ),
+    spotId: requireSpotId((value as { spotId: string }).spotId),
+    spotKind: (value as { spotKind?: unknown }).spotKind === ZLinkSpotKind.Entry
+      ? ZLinkSpotKind.Entry
+      : ZLinkSpotKind.User,
+    targetSpotGeneration: optionalBigInt(value, 'targetSpotGeneration'),
+    targetNodeGeneration: optionalBigInt(value, 'targetNodeGeneration'),
+    authorityOwnerGeneration: optionalBigInt(value, 'authorityOwnerGeneration'),
+    targetOwnerId: optionalString(value, 'targetOwnerId'),
+    ownerLeaseGeneration: optionalBigInt(value, 'ownerLeaseGeneration'),
+    authorityStoreVersion: optionalString(value, 'authorityStoreVersion')
+  };
+}
+
+function requireSpotId(value: string): string {
+  const bytes = Buffer.byteLength(value, 'utf8');
+  if (bytes < 1 || bytes > 255) {
+    throw new Error('Actor packet target SpotId must contain 1..255 UTF-8 bytes.');
+  }
+  return value;
+}
+
+export function decodeRemoteActorPacketRelayPayload(payload: unknown): {
+  readonly actorId: string;
+  readonly routerChannelId?: string;
+  readonly boundSessionTargetNodeRid?: string;
+  readonly boundSessionSpotId?: string;
+  readonly header: string;
+  readonly payload: string;
+  readonly actorNodeRid?: string;
+  readonly actorNodeRidHex?: string;
+  readonly actorGeneration?: string;
+  readonly bindingActorNodeRid?: string;
+  readonly bindingActorNodeRidHex?: string;
+  readonly bindingActorGeneration?: string;
+  readonly bindingGeneration?: string;
+  readonly returnResponse?: boolean;
+  readonly messageFollowContext?: ZLinkActorMessageFollowContext;
+} {
+  if (
+    typeof payload !== 'object' ||
+    payload === null ||
+    (payload as { packetName?: unknown }).packetName !== ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET ||
+    typeof (payload as { actorId?: unknown }).actorId !== 'string' ||
+    typeof (payload as { header?: unknown }).header !== 'string' ||
+    typeof (payload as { payload?: unknown }).payload !== 'string'
+  ) {
+    throw new Error('Remote actor packet relay payload is invalid.');
+  }
+  return {
+    actorId: (payload as { actorId: string }).actorId,
+    routerChannelId: optionalString(payload, 'routerChannelId'),
+    boundSessionTargetNodeRid: optionalString(payload, 'boundSessionTargetNodeRid'),
+    boundSessionSpotId: optionalString(payload, 'boundSessionSpotId'),
+    header: (payload as { header: string }).header,
+    payload: (payload as { payload: string }).payload,
+    actorNodeRid: optionalString(payload, 'actorNodeRid'),
+    actorNodeRidHex: optionalString(payload, 'actorNodeRidHex'),
+    actorGeneration: optionalString(payload, 'actorGeneration'),
+    bindingActorNodeRid: optionalString(payload, 'bindingActorNodeRid'),
+    bindingActorNodeRidHex: optionalString(payload, 'bindingActorNodeRidHex'),
+    bindingActorGeneration: optionalString(payload, 'bindingActorGeneration'),
+    bindingGeneration: optionalString(payload, 'bindingGeneration'),
+    returnResponse: (payload as { returnResponse?: unknown }).returnResponse === true,
+    messageFollowContext: decodeActorMessageFollowContext(
+      (payload as { messageFollowContext?: unknown }).messageFollowContext
+    )
+  };
+}
+
+function optionalString(value: object, key: string): string | undefined {
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === 'string' ? field : undefined;
+}
+
+function optionalBigInt(value: object, key: string): bigint | undefined {
+  const field = optionalString(value, key);
+  return field === undefined ? undefined : BigInt(field);
+}