@zlink-systems/framework 0.30.3 → 0.32.0

package/src/contracts/Common/HandlerMessageType.ts

@@ -0,0 +1,50 @@
+import type { Type, ZLinkMessageTypeResolver } from './CoreTypes';
+
+type HandlerTypeWithMessageType = Type & {
+  readonly messageType?: ZLinkMessageTypeResolver;
+};
+
+export interface ZLinkHandlerMessageType {
+  readonly type: Type;
+}
+
+/** Reads a handler's declared type once and defers/caches a lazy resolver until decode. */
+export function resolveHandlerMessageType(handlerType: Type): ZLinkHandlerMessageType | undefined {
+  const declared = (handlerType as HandlerTypeWithMessageType).messageType;
+  if (declared === undefined) return undefined;
+  if (isTypeConstructor(declared)) return { type: declared };
+
+  let state: 'unresolved' | 'resolved' | 'failed' = 'unresolved';
+  let resolved: Type | undefined;
+  let failure: unknown;
+  return {
+    get type() {
+      if (state === 'unresolved') {
+        try {
+          resolved = declared();
+          state = 'resolved';
+        } catch (error) {
+          failure = error;
+          state = 'failed';
+        }
+      }
+      if (state === 'failed') throw failure;
+      return resolved!;
+    }
+  };
+}
+
+/** Converts a stored registration resolver to the constructor expected by a codec. */
+export function resolveMessageTypeForDecode(
+  messageType?: ZLinkHandlerMessageType
+): Type | undefined {
+  return messageType?.type;
+}
+
+function isTypeConstructor(value: unknown): value is Type {
+  // Class constructors have a non-writable prototype property; ordinary resolver functions do not.
+  return (
+    typeof value === 'function' &&
+    Object.getOwnPropertyDescriptor(value, 'prototype')?.writable === false
+  );
+}

package/src/contracts/Common/ZLinkEncodedPayload.ts

@@ -1,16 +1,12 @@
-import {
-  adoptEncodedPayload,
-  borrowEncodedPayload,
-  storeEncodedPayload
-} from './encoded-payload-storage';
-
 export class ZLinkEncodedPayload {
+  readonly #bytes: Buffer;
+
   private constructor(bytes: Uint8Array, owned: boolean) {
-    if (owned) {
-      adoptEncodedPayload(this, bytes);
-    } else {
-      storeEncodedPayload(this, bytes);
-    }
+    this.#bytes = !owned
+      ? Buffer.from(bytes)
+      : Buffer.isBuffer(bytes)
+        ? bytes
+        : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   }
 
   /** Copies the supplied bytes. */
@@ -25,12 +21,12 @@ export class ZLinkEncodedPayload {
 
   /** Returns a copy of the stored bytes. */
   data(): Uint8Array {
-    return new Uint8Array(this.stored());
+    return new Uint8Array(this.#bytes);
   }
 
   /** Returns the stored bytes without copying. Do not modify this view or its backing buffer. */
   view(): Readonly<Uint8Array> {
-    return this.stored();
+    return this.#bytes;
   }
 
   toBytes(): Uint8Array {
@@ -38,30 +34,22 @@ export class ZLinkEncodedPayload {
   }
 
   copy(): ZLinkEncodedPayload {
-    return ZLinkEncodedPayload.from(this.stored());
+    return ZLinkEncodedPayload.from(this.#bytes);
   }
 
   size(): number {
-    return this.stored().length;
+    return this.#bytes.length;
   }
 
   isEmpty(): boolean {
-    return this.stored().length === 0;
+    return this.#bytes.length === 0;
   }
 
   getString(encoding: BufferEncoding = 'utf8'): string {
-    return this.stored().toString(encoding);
+    return this.#bytes.toString(encoding);
   }
 
   close(): void {
     // ZLinkEncodedPayload owns managed memory only; this mirrors Message-like readers.
   }
-
-  private stored(): Buffer {
-    const payload = borrowEncodedPayload(this);
-    if (payload === undefined) {
-      throw new Error('ZLink encoded payload storage is unavailable.');
-    }
-    return payload;
-  }
 }

package/src/contracts/Common/ZLinkMessage.ts

@@ -123,13 +123,17 @@ export function materializeZLinkMessageValue<T>(value: T, type?: Type<T>): T {
   }
 
   const materialized = Object.create(prototype) as Record<string, unknown>;
-  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-    Object.defineProperty(materialized, key, {
-      configurable: true,
-      enumerable: true,
-      value: item,
-      writable: true
-    });
+  const descriptor: PropertyDescriptor = {
+    configurable: true,
+    enumerable: true,
+    value: undefined,
+    writable: true
+  };
+  for (const key in value) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      descriptor.value = (value as Record<string, unknown>)[key];
+      Object.defineProperty(materialized, key, descriptor);
+    }
   }
   return materialized as T;
 }

package/src/contracts/Common/encoded-payload-storage.ts

@@ -1,19 +1,7 @@
-const encodedPayloadStorage = new WeakMap<object, Buffer>();
-
-export function storeEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
-  const stored = Buffer.from(bytes);
-  encodedPayloadStorage.set(owner, stored);
-  return stored;
-}
-
-export function adoptEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
-  const stored = Buffer.isBuffer(bytes)
-    ? bytes
-    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  encodedPayloadStorage.set(owner, stored);
-  return stored;
-}
+import { ZLinkEncodedPayload } from './ZLinkEncodedPayload';
 
 export function borrowEncodedPayload(owner: object): Buffer | undefined {
-  return encodedPayloadStorage.get(owner);
+  return owner instanceof ZLinkEncodedPayload
+    ? (ZLinkEncodedPayload.prototype.view.call(owner) as Buffer)
+    : undefined;
 }

package/src/contracts/Common/index.ts

@@ -1,5 +1,5 @@
 export * from './ActorRef';
-export type { Type, RoutingId, ActorId, SpotId } from './CoreTypes';
+export type { Type, ZLinkMessageTypeResolver, RoutingId, ActorId, SpotId } from './CoreTypes';
 export * from './ZLinkEncodedPayload';
 export * from './ZLinkMessageMetadata';
 export { ZLinkMessage, isZLinkMessage } from './ZLinkMessage';

package/src/contracts/Common/payload-slab.ts

@@ -0,0 +1,29 @@
+const SLAB_BYTES = 64 * 1024;
+const MAX_POOLED_BYTES = 16 * 1024;
+const ALIGNMENT = 8;
+
+let slab: Buffer | undefined;
+let offset = 0;
+
+/** Allocates independent bytes; previously returned regions are never reused. */
+export function allocatePayloadBytes(length: number): Buffer {
+  if (length > MAX_POOLED_BYTES || length < 0 || !Number.isInteger(length)) {
+    return Buffer.allocUnsafe(length);
+  }
+  if (slab === undefined || offset + length > SLAB_BYTES) {
+    slab = Buffer.allocUnsafe(SLAB_BYTES);
+    offset = 0;
+  }
+  const bytes = slab.subarray(offset, offset + length);
+  offset += Math.ceil(length / ALIGNMENT) * ALIGNMENT;
+  // Transient runtime frames only; local queues and application boundaries
+  // copy before they retain or expose these bytes.
+  return bytes;
+}
+
+/** Copies bytes into an exact, standalone backing store with no Buffer pool. */
+export function copyPayloadBytes(bytes: Uint8Array): Buffer {
+  const copy = Buffer.allocUnsafeSlow(bytes.byteLength);
+  copy.set(bytes);
+  return copy;
+}

package/src/contracts/Configuration/RegistrationBuilders.ts

@@ -1,3 +1,4 @@
+import type { ZLinkHandlerMessageType } from '../Common/HandlerMessageType';
 import { AutoHwmProfile } from '@zlink-systems/zlink';
 import type {
   RoutingId,
@@ -53,6 +54,7 @@ import { requireMessageFlowLogMode, requireTraceSampleRate } from './Diagnostics
 import { normalizeEndpoint } from './EndpointNotation';
 import { requirePublicFanoutTopic } from './FanoutTopic';
 import { requireValidSendTimeoutMs } from './SendTimeoutValidation';
+import { resolveHandlerMessageType } from '../Common/HandlerMessageType';
 import { DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE } from './InternalDefaults';
 import {
   type ZLinkActorFactoryBuilder,
@@ -671,7 +673,7 @@ class DefaultClientServerChannelServerBuilder implements ZLinkClientServerChanne
     handlerType: Type<import('../Handlers').ZLinkSendHandler<TMessage>>
   ): this {
     this.channel.sendHandlers ??= [];
-    this.channel.sendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+    this.channel.sendHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 
@@ -679,7 +681,7 @@ class DefaultClientServerChannelServerBuilder implements ZLinkClientServerChanne
     handlerType: Type<import('../Handlers').ZLinkRequestHandler<TRequest, TReply>>
   ): this {
     this.channel.requestHandlers ??= [];
-    this.channel.requestHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+    this.channel.requestHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 
@@ -1011,7 +1013,7 @@ class DefaultMeshNodeBuilder implements ZLinkMeshNodeBuilder {
     handlerType: Type<import('../Handlers').ZLinkRouteSendHandler<TMessage>>
   ): this {
     this.node.routeSendHandlers ??= [];
-    this.node.routeSendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+    this.node.routeSendHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 
@@ -1019,10 +1021,7 @@ class DefaultMeshNodeBuilder implements ZLinkMeshNodeBuilder {
     handlerType: Type<import('../Handlers').ZLinkRouteRequestHandler<TRequest, TReply>>
   ): this {
     this.node.routeRequestHandlers ??= [];
-    this.node.routeRequestHandlers.push({
-      packetName: handlerPacketName(handlerType),
-      handlerType
-    });
+    this.node.routeRequestHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 
@@ -1379,7 +1378,7 @@ class DefaultMeshChannelServerBuilder implements ZLinkMeshChannelServerBuilder {
     handlerType: Type<import('../Handlers').ZLinkSendHandler<TMessage>>
   ): this {
     this.channel.sendHandlers ??= [];
-    this.channel.sendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+    this.channel.sendHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 
@@ -1387,7 +1386,7 @@ class DefaultMeshChannelServerBuilder implements ZLinkMeshChannelServerBuilder {
     handlerType: Type<import('../Handlers').ZLinkRequestHandler<TRequest, TReply>>
   ): this {
     this.channel.requestHandlers ??= [];
-    this.channel.requestHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+    this.channel.requestHandlers.push(handlerRegistration(handlerType));
     return this;
   }
 }
@@ -1588,8 +1587,8 @@ interface MutableChannelOptions {
   client?: MutableClientCapabilityOptions;
   server?: MutableServerCapabilityOptions;
   handlerGroups?: string[];
-  requestHandlers?: Array<{ packetName: string; handlerType: Type }>;
-  sendHandlers?: Array<{ packetName: string; handlerType: Type }>;
+  requestHandlers?: MutableHandlerRegistration[];
+  sendHandlers?: MutableHandlerRegistration[];
 }
 
 interface MutableServerCapabilityOptions {
@@ -1670,8 +1669,8 @@ interface MutableSpotNodeOptions {
     MutableObjectFactoryRegistration<ZLinkActor, ZLinkActorFactory, ZLinkActorFactoryConfiguration>
   >;
   meshChannels?: Record<string, MutableMeshChannelOptions>;
-  routeSendHandlers?: Array<{ packetName: string; handlerType: Type }>;
-  routeRequestHandlers?: Array<{ packetName: string; handlerType: Type }>;
+  routeSendHandlers?: MutableHandlerRegistration[];
+  routeRequestHandlers?: MutableHandlerRegistration[];
   requestTimeoutMs?: number;
 }
 
@@ -1686,8 +1685,8 @@ interface MutableMeshChannelOptions {
   server?: boolean;
   weight?: number;
   handlerGroups?: string[];
-  sendHandlers?: Array<{ packetName: string; handlerType: Type }>;
-  requestHandlers?: Array<{ packetName: string; handlerType: Type }>;
+  sendHandlers?: MutableHandlerRegistration[];
+  requestHandlers?: MutableHandlerRegistration[];
 }
 
 interface MutableSpotRouterCapabilityOptions {
@@ -1709,6 +1708,21 @@ interface MutableSpotPubSubCapabilityOptions {
   routingId?: string;
 }
 
+interface MutableHandlerRegistration {
+  packetName: string;
+  handlerType: Type;
+  messageType?: ZLinkHandlerMessageType;
+}
+
+function handlerRegistration(handlerType: Type): MutableHandlerRegistration {
+  const messageType = resolveHandlerMessageType(handlerType);
+  return {
+    packetName: handlerPacketName(handlerType),
+    handlerType,
+    ...(messageType === undefined ? {} : { messageType })
+  };
+}
+
 function handlerPacketName(handlerType: Type): string {
   return (
     readZLinkDecoratorMetadata(handlerType).find(

package/src/contracts/Configuration/RegistrationTypes.ts

@@ -1,3 +1,4 @@
+import type { ZLinkHandlerMessageType } from '../Common/HandlerMessageType';
 import type {
   RoutingId,
   Type,
@@ -327,21 +328,25 @@ export interface ZLinkMeshChannelOptions {
 export interface ZLinkMeshSendHandlerRegistration {
   readonly packetName: string;
   readonly handlerType: Type;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkMeshRequestHandlerRegistration {
   readonly packetName: string;
   readonly handlerType: Type;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkRouteMeshSendHandlerRegistration {
   readonly packetName: string;
   readonly handlerType: Type;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkRouteMeshRequestHandlerRegistration {
   readonly packetName: string;
   readonly handlerType: Type;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkEntrySpotTimerHandlerRegistration {
@@ -356,6 +361,7 @@ export interface ZLinkEntrySpotPacketHandlerRegistration {
   readonly entrySpotType: Type<ZLinkEntrySpot>;
   readonly handlerType: Type;
   readonly packetName?: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkEntrySpotSubscriptionHandlerRegistration {
@@ -363,6 +369,7 @@ export interface ZLinkEntrySpotSubscriptionHandlerRegistration {
   readonly handlerType: Type;
   readonly channelName: string;
   readonly topic: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkEntrySpotActorSendHandlerRegistration {
@@ -370,6 +377,7 @@ export interface ZLinkEntrySpotActorSendHandlerRegistration {
   readonly actorType: Type<ZLinkActor>;
   readonly handlerType: Type;
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkEntrySpotActorRequestHandlerRegistration {
@@ -377,6 +385,7 @@ export interface ZLinkEntrySpotActorRequestHandlerRegistration {
   readonly actorType: Type<ZLinkActor>;
   readonly handlerType: Type;
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkSpotTimerHandlerRegistration {
@@ -391,6 +400,7 @@ export interface ZLinkSpotPacketHandlerRegistration {
   readonly spotType: Type<ZLinkSpot>;
   readonly handlerType: Type;
   readonly packetName?: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkSpotSubscriptionHandlerRegistration {
@@ -398,6 +408,7 @@ export interface ZLinkSpotSubscriptionHandlerRegistration {
   readonly handlerType: Type;
   readonly channelName: string;
   readonly topic: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkSpotActorSendHandlerRegistration {
@@ -405,6 +416,7 @@ export interface ZLinkSpotActorSendHandlerRegistration {
   readonly actorType: Type<ZLinkActor>;
   readonly handlerType: Type;
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkSpotActorRequestHandlerRegistration {
@@ -412,6 +424,7 @@ export interface ZLinkSpotActorRequestHandlerRegistration {
   readonly actorType: Type<ZLinkActor>;
   readonly handlerType: Type;
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkSpotRouterCapabilityOptions {
@@ -442,25 +455,30 @@ export interface ZLinkRouteChannelHandlerOptions {
   readonly kind: 'send' | 'request';
   readonly packetName: string;
   readonly handler: ZLinkRouteChannelSendHandler | ZLinkRouteChannelRequestHandler;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkRouteChannelSendHandlerRegistration {
   readonly packetName: string;
   readonly handler: ZLinkRouteChannelSendHandler;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkRouteChannelRequestHandlerRegistration {
   readonly packetName: string;
   readonly handler: ZLinkRouteChannelRequestHandler;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkChannelPublishHandlerRegistration {
   readonly packetName: string;
   readonly handler: ZLinkChannelPublishHandler;
+  readonly messageType?: ZLinkHandlerMessageType;
 }
 
 export interface ZLinkChannelRequestHandlerRegistration {
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
   readonly handler?: {
     handle(payload: unknown, context: ZLinkMessageContext): Promise<unknown>;
   };
@@ -469,6 +487,7 @@ export interface ZLinkChannelRequestHandlerRegistration {
 
 export interface ZLinkChannelSendHandlerRegistration {
   readonly packetName: string;
+  readonly messageType?: ZLinkHandlerMessageType;
   readonly handler?: {
     handle(payload: unknown, context: ZLinkMessageContext): Promise<void>;
   };

package/src/contracts/Handlers/Contexts.ts

@@ -7,6 +7,7 @@ export interface ZLinkMessageContext {
   readonly contentType?: string;
   readonly metadata: ZLinkMessageMetadata;
   readonly correlationId?: string;
+  readonly receivedAt: Date;
 }
 
 export interface ZLinkPublishMessageContext extends ZLinkMessageContext {

package/src/contracts/Locations/Authority.ts

@@ -1,3 +1,4 @@
+import type { ZLinkFrameworkErrorKind } from '../Errors';
 import type { RoutingId } from '../Common';
 import type { ZLinkMeshNodeDescriptorKey } from './Keys';
 import type { ZLinkLocationOwnerToken } from './Writes';
@@ -93,7 +94,12 @@ export type ZLinkAuthorityCompareExchangeResult =
       readonly storeVersion: ZLinkAuthorityStoreVersion;
       readonly storeNow: Date;
     }
-  | { readonly kind: 'conflict'; readonly current: ZLinkAuthorityReadResult }
+  | {
+      readonly kind: 'conflict';
+      readonly current: ZLinkAuthorityReadResult;
+      readonly membershipFailure?:
+        ZLinkFrameworkErrorKind.NotFound | ZLinkFrameworkErrorKind.Unavailable;
+    }
   | { readonly kind: 'generationExhausted' };
 
 export interface ZLinkAuthorityEntry {

package/src/internal.ts

@@ -3,6 +3,19 @@ export * from './index';
 export { requireValidSendTimeoutMs } from './contracts/Configuration/SendTimeoutValidation';
 export * from './runtime/diagnostics';
 export * from './runtime/host';
+export { ZLinkActorPlacementCoordinator } from './runtime/host/actor-placement-coordinator';
+export { ZLinkActorTransferRuntime } from './runtime/host/actor-transfer-runtime';
+export {
+  ApplicationJobQueue,
+  ApplicationJobQueuePermit,
+  nodeEffectiveProcessorCount,
+  resolveApplicationJobQueueConfiguration
+} from './runtime/host/application-job-queue';
+export { ZLinkLocationRuntimeOwner } from './runtime/host/location-runtime-owner';
+export {
+  relocationFailedFailureCode,
+  ZLinkHostServiceRelocationRuntime
+} from './runtime/host/service-relocation-host-runtime';
 export * from './runtime/admission';
 export * from './runtime/activation-admission';
 export * from './runtime/streams';
@@ -21,9 +34,13 @@ export {
 } from './contracts/Locations/Values';
 export { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from './contracts/Locations/Writes';
 export * from './runtime/channels';
+export { ZLinkChannelRuntimeLifecycle } from './runtime/channels/channel-runtime-lifecycle';
+export { ZLinkChannelSocketRegistry } from './runtime/channels/channel-socket-registry';
+export { ZLinkChannelDispatchPipeline } from './runtime/channels/channel-dispatch-pipeline';
 export * from './runtime/backend';
 export * from './runtime/codecs';
 export * from './runtime/execution';
+export { ZLinkSerialExecutionQueue } from './runtime/execution/serial-execution-queue';
 export * from './runtime/handlers';
 export * from './runtime/messaging';
 export * from './runtime/foundation';

package/src/nest-integration.ts

@@ -19,6 +19,7 @@ export {
   validateMessageFollowDuration,
   validateSessionReplacementCallbackTimeout
 } from './contracts/Configuration/RegistrationBuilderPolicy';
+export { resolveHandlerMessageType } from './contracts/Common/HandlerMessageType';
 
 import type {
   ZLinkLocationRuntimeQuery,