@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/backend/contracts/index.ts

@@ -6,7 +6,7 @@ import type {
   ZLinkBackendReceived,
   ZLinkBackendTopicMessage
 } from '../runtime-values';
-import type { CoreHwmBudgetSnapshot } from '@zlink-systems/zlink';
+import type { CoreHwmBudgetSnapshot, ReceiveFlowState } from '@zlink-systems/zlink';
 import { type ZLinkBackendRecvFlags, type ZLinkBackendSendFlags } from '../runtime-values';
 export * from '../runtime-values';
 type MessageLike = ZLinkBackendMessageLike;
@@ -27,6 +27,7 @@ import type {
 import type { RoutingId } from '../../../contracts';
 import type { ZLinkCoreHwmOptions } from '../../../contracts/Configuration';
 import type { ZLinkSubmitResult } from '../../messaging/submission-result';
+import type { ZLinkMeshCompletionHandler } from '../mesh-completion-table';
 import type { Message } from '../../../contracts/Common/Message';
 import type {
   ServiceSpotMessageFollowSeal,
@@ -38,6 +39,7 @@ import type {
   ServiceActorCreateRecord,
   ServiceDirectSpotRouteFence,
   ServiceInstanceRouteFence,
+  ServiceInstanceColdActivationTarget,
   ServiceUserSpotCloseRecord,
   ServiceUserSpotCreateRecord
 } from '../../foundation/service-stateful-wire-codec';
@@ -60,6 +62,7 @@ export type ZLinkBackendObjectPlacement =
   | { readonly kind: 'unavailable' };
 
 export interface ZLinkBackendMeshNode {
+  readonly routingId?: RoutingId;
   completeClosedInstance?(spotId: string, objectGeneration: bigint): void;
   setDispatchErrorReporter?(
     reporter: import('../../channels/dispatch-error-reporter').ZLinkDispatchErrorReporter,
@@ -112,30 +115,19 @@ export interface ZLinkBackendMeshNode {
   selectObjectPlacement(stableType: string): ZLinkBackendObjectPlacement;
   instanceSpotPlacementTypes?(): readonly string[];
   sendToMissingInstanceSpot(
-    target: {
-      readonly targetNodeRid: string;
-      readonly targetNodeGeneration: bigint;
-      readonly targetSpotId: string;
-      readonly stableType: string;
-      readonly descriptorVersion: string;
-    },
+    target: ServiceInstanceColdActivationTarget,
     parts: ZLinkBackendMessageLike | readonly ZLinkBackendMessageLike[],
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
     metadata?: ReadonlyMap<string, string>
   ): Promise<SubmitResult>;
   requestToMissingInstanceSpot(
-    target: {
-      readonly targetNodeRid: string;
-      readonly targetNodeGeneration: bigint;
-      readonly targetSpotId: string;
-      readonly stableType: string;
-      readonly descriptorVersion: string;
-    },
+    target: ServiceInstanceColdActivationTarget,
     parts: ZLinkBackendMessageLike | readonly ZLinkBackendMessageLike[],
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): MeshOperationId;
   sendToInstanceSpot(
     route: ServiceInstanceRouteFence,
@@ -150,7 +142,8 @@ export interface ZLinkBackendMeshNode {
     timeoutMs?: number,
     sourceSpotId?: string,
     metadata?: ReadonlyMap<string, string>,
-    instanceIntent?: boolean
+    instanceIntent?: boolean,
+    onAdmitted?: () => void
   ): MeshOperationId;
   registerUserSpotOperationHandler(handler: ServiceUserSpotOperationHandler): void;
   requestUserSpotCreate(
@@ -192,12 +185,16 @@ export interface ZLinkBackendMeshNode {
     readonly lifecycleGeneration: bigint;
   }): void;
   isObjectClientNodeDirectTarget?(targetRid: unknown): boolean;
+  observePeerRoute?(
+    targetRid: unknown
+  ): import('../../foundation/durable-service-request').PeerRouteObservation;
+  hasPeerRouteOrConnectionIntent?(targetRid: unknown, endpoint: string): boolean;
   isPeerRouteReady?(targetRid: unknown, lifecycleGeneration?: bigint): boolean;
   sendToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
     options?: { flags?: number }
-  ): Promise<SubmitResult>;
+  ): SubmitResult | Promise<SubmitResult>;
   /**
    * Sends service-wire infrastructure frames directly to a peer. Relocation
    * Prepare may add NODE-INTERNAL sideband frames after its canonical frame.
@@ -218,12 +215,21 @@ export interface ZLinkBackendMeshNode {
   requestInfrastructureControlFrames?(
     targetRid: unknown,
     frames: readonly Uint8Array[],
-    options?: { readonly timeoutMs?: number }
+    options?: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onSubmitted?: (signal: AbortSignal) => Promise<void>;
+    }
   ): Promise<readonly Uint8Array[]>;
   requestToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendToChannel(
     channelName: string,
@@ -233,7 +239,12 @@ export interface ZLinkBackendMeshNode {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   status(): MeshNodeStatus;
   peers(): MeshPeerEntry[];
@@ -359,7 +370,12 @@ export interface ZLinkBackendMeshNode {
   requestToActor(
     actor: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   actorSendToActor(
     source: ZLinkBackendActorRef,
@@ -371,7 +387,12 @@ export interface ZLinkBackendMeshNode {
     source: ZLinkBackendActorRef,
     target: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendActorBoundSession(
     actor: ZLinkBackendActorRef,
@@ -390,6 +411,7 @@ export interface ZLinkBackendMeshNode {
     timeoutMs?: number
   ): MeshOperationId;
   setReadyHandler(handler: (readyDomains: number) => number): void;
+  setCompletionHandler(handler: ZLinkMeshCompletionHandler): void;
   createReadyBatch(capacity: number): ReadyBatch;
   createReceiveBatch(messageCapacity: number, partCapacity: number): ReceiveBatch;
   drainReady(
@@ -476,7 +498,6 @@ export interface ZLinkBackendSocket extends ZLinkBackendObject {
   readonly lastEndpoint?: string;
   bind(endpoint: string): void;
   setChannelName(channelName: string): void;
-  setReceiveFlowState?(state: 0 | 1): void;
   dispose(): Promise<void>;
 }
 
@@ -486,7 +507,7 @@ export interface ZLinkBackendConnectableSocket extends ZLinkBackendSocket {
 }
 
 export interface ZLinkBackendDealerSocket extends ZLinkBackendConnectableSocket {
-  setReceiveFlowState(state: 0 | 1): void;
+  receiveAdmission?: import('../../foundation/service-liveness-registry').ServiceLivenessConnection;
   setRoutingId(routingId: RoutingId): void;
   peerWeight: number;
   sendHighWaterMark: number;
@@ -494,7 +515,11 @@ export interface ZLinkBackendDealerSocket extends ZLinkBackendConnectableSocket
   receiveTimeoutMs: number;
   maxMessageSize: number;
   send(message: Message | readonly Message[]): Promise<void>;
-  request(message: Message | readonly Message[], timeoutMs?: number): Promise<readonly Message[]>;
+  request(
+    message: Message | readonly Message[],
+    timeoutMs?: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Message[]>;
   recv(flags?: ZLinkBackendRecvFlags): Received | undefined;
 }
 
@@ -511,11 +536,11 @@ export interface ZLinkBackendSendOperation {
 export interface ZLinkBackendRequestOperation {
   message(message: MessageLike): ZLinkBackendRequestOperation;
   timeout(timeoutMs: number): ZLinkBackendRequestOperation;
-  submit(): Promise<readonly Message[]>;
+  submit(onAdmitted?: () => void): Promise<readonly Message[]>;
 }
 
 export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket {
-  setReceiveFlowState(state: 0 | 1): void;
+  setReceiveFlowState(state: ReceiveFlowState): void;
   /** Enables the native probe handshake for manually configured routes. */
   setProbe(enabled: boolean): void;
   peerWeight: number;
@@ -529,7 +554,8 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
   request(
     routingId: RoutingId,
     message: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   sendToSpot(
     targetNodeRid: RoutingId,
@@ -541,7 +567,8 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
     targetNodeRid: RoutingId,
     targetSpotId: RoutingId,
     parts: readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   disconnectPeer(routingId: RoutingId): void;
   reply(routingId: RoutingId, replyToken: unknown): ZLinkBackendReplyOperation;
@@ -549,6 +576,7 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
 }
 
 export interface ZLinkBackendPublisherSocket extends ZLinkBackendSocket {
+  lingerMs: number;
   sendTimeoutMs: number;
   sendHighWaterMark: number;
   noDrop: boolean;
@@ -697,7 +725,8 @@ export interface ZLinkBackendSpot extends ZLinkBackendObject {
   requestToChannel(
     channelName: string,
     payload: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   sendToChannel(channelName: string, payload: Message | readonly Message[]): Promise<void>;
   publish(
@@ -714,7 +743,8 @@ export interface ZLinkBackendSpot extends ZLinkBackendObject {
     targetRid: RoutingId,
     spotId: RoutingId,
     payload: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   dispose(): Promise<void>;
 }
@@ -739,6 +769,7 @@ export interface ZLinkMeshBackendAdapter {
       readonly trustProfile?: string;
       readonly applicationJobQueue: import('../../application-jobs/contracts').ApplicationJobQueuePort;
       readonly applicationJobReceiveFlowFailureSink?: (error: unknown) => void;
+      readonly infrastructureTaskRunner?: import('../../spots/spot-actor-join-dispatch').ZLinkDetachedTaskRunner;
       readonly peerAdmissionSealed?: () => boolean;
     }
   ): ZLinkBackendMeshNode;

package/src/runtime/backend/mesh-completion-table.ts

@@ -5,7 +5,7 @@ import type {
   ReceiveKindData,
   ReceiveRecord
 } from '../foundation/service-runtime-contracts';
-import { operationIdentityKey } from '../foundation/operation-identity';
+import { operationIdentityKey, validateOperationIdentity } from '../foundation/operation-identity';
 
 export interface ZLinkMeshCompletionDiagnostic {
   readonly kind: 'unknownOrLate';
@@ -21,25 +21,128 @@ export interface ZLinkMeshCompletion {
   readonly parts: Message[];
 }
 
-interface PendingCompletion {
-  readonly resolve: (completion: ZLinkMeshCompletion) => void;
-  readonly reject: (error: unknown) => void;
-  readonly removeAbort?: () => void;
+const COMPLETION_SLOT_BLOCK_SIZE = 64;
+const COMPLETION_HASH_BUCKETS_PER_SLOT = 2;
+const COMPLETION_HASH_WORD_SCALE = 0x1_0000;
+const COMPLETION_HASH_MULTIPLIER = 0x9e37_79b1;
+const COMPLETION_ABORT_OPTIONS = Object.freeze({ once: true });
+
+class CompletionSlot {
+  generation = 0;
+  next = -1;
+  high?: bigint;
+  low?: bigint;
+  hashNext = -1;
+  resolve?: (completion: ZLinkMeshCompletion) => void;
+  reject?: (error: unknown) => void;
+  signal?: AbortSignal;
+
+  constructor(readonly abort: () => void) {}
 }
 
+export type ZLinkMeshCompletionTerminal = Pick<ReceiveRecord, 'operationId' | 'terminalResult'>;
+export type ZLinkMeshCompletionHandler = (
+  terminal: ZLinkMeshCompletionTerminal,
+  materialize: () => ReceiveRecord
+) => void;
+
 export class ZLinkMeshCompletionTable {
-  private readonly pending = new Map<string, PendingCompletion>();
+  private buckets = new Int32Array(0);
+  private readonly slots: CompletionSlot[] = [];
+  private free = -1;
+  private activeCount = 0;
   private disposed = false;
 
-  constructor(
-    private readonly onDiagnostic?: (diagnostic: ZLinkMeshCompletionDiagnostic) => void
-  ) {}
+  constructor(private readonly onDiagnostic?: (diagnostic: ZLinkMeshCompletionDiagnostic) => void) {
+    this.prepareSlots();
+  }
+
+  private prepareSlots(): void {
+    const start = this.slots.length;
+    for (let index = start; index < start + COMPLETION_SLOT_BLOCK_SIZE; index++) {
+      const slot = new CompletionSlot(() => {
+        const reject = slot.reject;
+        const signal = slot.signal;
+        if (reject === undefined) return;
+        this.releaseSlot(index);
+        reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+      });
+      slot.next = this.free;
+      this.slots.push(slot);
+      this.free = index;
+    }
+    const minimumBuckets = this.slots.length * COMPLETION_HASH_BUCKETS_PER_SLOT;
+    this.buckets = new Int32Array(2 ** Math.ceil(Math.log2(minimumBuckets))).fill(-1);
+    for (let index = 0; index < this.slots.length; index++) {
+      const slot = this.slots[index]!;
+      if (slot.high === undefined) continue;
+      this.indexSlot(index);
+    }
+  }
+
+  private bucket(high: bigint, low: bigint): number {
+    const highWord = Number(high);
+    const lowWord = Number(low);
+    // Bucket selection may collide; the stored 128-bit identity is compared exactly.
+    const hash =
+      Math.imul(
+        highWord ^ Math.trunc(highWord / COMPLETION_HASH_WORD_SCALE),
+        COMPLETION_HASH_MULTIPLIER
+      ) ^
+      lowWord ^
+      Math.trunc(lowWord / COMPLETION_HASH_WORD_SCALE);
+    return hash & (this.buckets.length - 1);
+  }
+
+  private indexSlot(index: number): void {
+    const slot = this.slots[index]!;
+    const bucket = this.bucket(slot.high!, slot.low!);
+    slot.hashNext = this.buckets[bucket]!;
+    this.buckets[bucket] = index;
+  }
+
+  private findSlot(operationId: MeshOperationId): number {
+    validateOperationIdentity(operationId);
+    for (
+      let index = this.buckets[this.bucket(operationId.high, operationId.low)]!;
+      index !== -1;
+      index = this.slots[index]!.hashNext
+    ) {
+      const slot = this.slots[index]!;
+      if (slot.high === operationId.high && slot.low === operationId.low) return index;
+    }
+    return -1;
+  }
+
+  private releaseSlot(index: number): void {
+    const slot = this.slots[index]!;
+    if (slot.high !== undefined) {
+      const bucket = this.bucket(slot.high, slot.low!);
+      let previous = -1;
+      let current = this.buckets[bucket]!;
+      while (current !== index) {
+        previous = current;
+        current = this.slots[current]!.hashNext;
+      }
+      if (previous === -1) this.buckets[bucket] = slot.hashNext;
+      else this.slots[previous]!.hashNext = slot.hashNext;
+    }
+    slot.signal?.removeEventListener('abort', slot.abort);
+    slot.high = undefined;
+    slot.low = undefined;
+    slot.hashNext = -1;
+    slot.signal = undefined;
+    slot.resolve = undefined;
+    slot.reject = undefined;
+    slot.next = this.free;
+    this.free = index;
+    this.activeCount--;
+  }
 
   /**
-   * Submits and registers without yielding control to the event loop. Mesh
-   * completion dispatch is asynchronous, so a completion cannot overtake the
-   * registration. The table therefore does not need to retain responses that
-   * arrived before their waiter.
+   * Reserves the dispatcher slot before transport submission. The backend
+   * observes native terminals through Promises, so identity binding finishes
+   * before the terminal callback can run, without an infrastructure pump.
    */
   submit(operation: () => MeshOperationId, signal?: AbortSignal): Promise<ZLinkMeshCompletion> {
     if (this.isDisposed()) {
@@ -50,32 +153,33 @@ export class ZLinkMeshCompletionTable {
         signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')
       );
     }
-    const operationId = operation();
-    // The backend submission callback can synchronously re-enter `dispose()`.
-    // TypeScript's control-flow analysis cannot observe mutation through it.
-    if (this.disposed) {
-      return Promise.reject(new Error('Mesh completion table is disposed.'));
-    }
-    const key = operationIdentityKey(operationId);
-    if (this.pending.has(key)) {
-      return Promise.reject(new Error(`Mesh operation '${key}' is already pending.`));
-    }
     return new Promise((resolve, reject) => {
-      const abort = () => {
-        this.pending.delete(key);
-        reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
-      };
-      if (signal?.aborted === true) {
-        abort();
-        return;
+      if (this.free === -1) this.prepareSlots();
+      const index = this.free;
+      const slot = this.slots[index]!;
+      this.free = slot.next;
+      const generation = ++slot.generation;
+      slot.resolve = resolve;
+      slot.reject = reject;
+      slot.signal = signal;
+      this.activeCount++;
+      try {
+        signal?.addEventListener('abort', slot.abort, COMPLETION_ABORT_OPTIONS);
+        const operationId = operation();
+        // A reentrant abort may release and reuse this slot during submission.
+        if (slot.generation !== generation || slot.resolve !== resolve) return;
+        if (this.findSlot(operationId) !== -1) {
+          throw new Error(
+            `Mesh operation '${operationIdentityKey(operationId)}' is already pending.`
+          );
+        }
+        slot.high = operationId.high;
+        slot.low = operationId.low;
+        this.indexSlot(index);
+      } catch (error) {
+        if (slot.generation === generation && slot.resolve === resolve) this.releaseSlot(index);
+        reject(error);
       }
-      signal?.addEventListener('abort', abort, { once: true });
-      this.pending.set(key, {
-        resolve,
-        reject,
-        removeAbort:
-          signal === undefined ? undefined : () => signal.removeEventListener('abort', abort)
-      });
     });
   }
 
@@ -83,10 +187,11 @@ export class ZLinkMeshCompletionTable {
     return this.disposed;
   }
 
-  complete(record: ReceiveRecord): void {
-    const key = operationIdentityKey(record.operationId);
-    const pending = this.pending.get(key);
-    if (pending === undefined) {
+  complete(record: ReceiveRecord): void;
+  complete(record: ZLinkMeshCompletionTerminal, materialize: () => ReceiveRecord): void;
+  complete(record: ZLinkMeshCompletionTerminal, materialize?: () => ReceiveRecord): void {
+    const index = this.findSlot(record.operationId);
+    if (index === -1) {
       this.onDiagnostic?.({
         kind: 'unknownOrLate',
         operationId: Object.freeze({ ...record.operationId }),
@@ -94,12 +199,16 @@ export class ZLinkMeshCompletionTable {
       });
       return;
     }
-    this.pending.delete(key);
-    pending.removeAbort?.();
+    const slot = this.slots[index]!;
+    const resolve = slot.resolve!;
+    const reject = slot.reject!;
+    this.releaseSlot(index);
     try {
-      pending.resolve(retainCompletion(record));
+      resolve(
+        retainCompletion(materialize === undefined ? (record as ReceiveRecord) : materialize())
+      );
     } catch (error) {
-      pending.reject(error);
+      reject(error);
     }
   }
 
@@ -108,36 +217,43 @@ export class ZLinkMeshCompletionTable {
       return;
     }
     this.disposed = true;
-    const pending = [...this.pending.values()];
-    this.pending.clear();
-    for (const entry of pending) {
-      entry.removeAbort?.();
-    }
-    for (const entry of pending) {
-      entry.reject(reason);
+    for (let index = 0; index < this.slots.length; index++) {
+      const reject = this.slots[index]!.reject;
+      if (reject === undefined) continue;
+      this.releaseSlot(index);
+      reject(reason);
     }
   }
 
   get pendingCount(): number {
-    return this.pending.size;
+    return this.activeCount;
   }
 }
 
 function retainCompletion(record: ReceiveRecord): ZLinkMeshCompletion {
+  const parts = retainCompletionParts(record.parts);
+  // The retention pass verifies every part is already a managed runtime message.
+  if (parts === record.parts) return record as unknown as ZLinkMeshCompletion;
   return {
     terminalResult: record.terminalResult,
     failureErrno: record.failureErrno,
     operationKind: record.operationKind,
     kindData: record.kindData,
-    parts: record.parts.map(retainCompletionPart)
+    parts
   };
 }
 
-function retainCompletionPart(part: ZLinkMessage): Message {
-  // A runtime message already owns a managed Buffer and close() is a no-op.
-  // Binding-native messages can expose native storage through data(), which
-  // becomes invalid when their owner closes; materialize that one boundary copy.
-  return part instanceof Message ? part : Message.fromOwned(Buffer.from(part.data()));
+function retainCompletionParts(parts: readonly ZLinkMessage[]): Message[] {
+  // Reuse managed messages and wrap binding payloads in the runtime representation.
+  let retained: Message[] | undefined;
+  for (let index = 0; index < parts.length; index++) {
+    const part = parts[index]!;
+    if (!(part instanceof Message)) {
+      retained ??= parts.slice() as Message[];
+      retained[index] = Message.fromOwned(Message.retainPayload(part));
+    }
+  }
+  return retained ?? (parts as Message[]);
 }
 
 export function closeMeshCompletion(completion: ZLinkMeshCompletion): void {