@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/foundation/service-liveness-registry.ts

@@ -54,9 +54,20 @@ export class ServiceLivenessConnection {
 }
 
 /** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
+const NO_LIVENESS_WORK: ServiceLivenessTick = Object.freeze({
+  probes: Object.freeze([]) as readonly ServiceProbe[],
+  timedOutNodes: Object.freeze([]) as readonly string[]
+});
+
 export class ServiceLivenessRegistry {
   private readonly peers = new Map<string, ServiceLivenessConnection>();
   private nextProbeId = 1n;
+  /**
+   * The earliest probe or timeout among admitted peers. Received traffic only
+   * extends a peer's deadline, so this stays a lower bound between ticks.
+   */
+  private nextDueMs = Number.POSITIVE_INFINITY;
+  private admissionActivityMs?: number;
 
   constructor(
     private readonly probeIntervalMs = DEFAULT_SERVICE_PROBE_INTERVAL_MS,
@@ -89,9 +100,33 @@ export class ServiceLivenessRegistry {
       this.peerTimeoutMs
     );
     this.peers.set(nodeRoutingId, admitted);
+    this.nextDueMs = Math.min(this.nextDueMs, admitted.nextProbeMs, admitted.deadlineMs);
     return admitted;
   }
 
+  /** When the next tick has probe or timeout work (spec 08 §4.2 management deadline). */
+  nextDeadlineMs(): number {
+    return Math.min(this.nextDueMs, this.nextAdmissionDeadlineMs());
+  }
+
+  /** Pending admission shares the existing liveness management cadence (MeshNode §7.1). */
+  setAdmissionPending(pending: boolean, nowMs: number): void {
+    if (pending) this.admissionActivityMs ??= nowMs;
+    else this.admissionActivityMs = undefined;
+  }
+
+  private nextAdmissionDeadlineMs(): number {
+    return this.admissionActivityMs === undefined
+      ? Number.POSITIVE_INFINITY
+      : this.admissionActivityMs + this.probeIntervalMs;
+  }
+
+  tickAdmission(nowMs: number): boolean {
+    if (nowMs < this.nextAdmissionDeadlineMs()) return false;
+    this.admissionActivityMs = nowMs;
+    return true;
+  }
+
   recordReceived(connection: ServiceLivenessConnection, nowMs: number): void {
     connection.recordReceived(nowMs);
   }
@@ -127,8 +162,10 @@ export class ServiceLivenessRegistry {
   }
 
   tick(nowMs: number): ServiceLivenessTick {
+    if (nowMs < this.nextDeadlineMs()) return NO_LIVENESS_WORK;
     const probes: ServiceProbe[] = [];
     const timedOutNodes: string[] = [];
+    let nextDueMs = Number.POSITIVE_INFINITY;
     for (const [nodeRoutingId, peer] of this.peers) {
       if (peer.isExpired(nowMs)) {
         timedOutNodes.push(nodeRoutingId);
@@ -138,7 +175,9 @@ export class ServiceLivenessRegistry {
       const probeId = peer.tryGetProbe(nowMs, this.allocateProbeId);
       if (probeId !== undefined)
         probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId });
+      nextDueMs = Math.min(nextDueMs, peer.nextProbeMs, peer.deadlineMs);
     }
+    this.nextDueMs = nextDueMs;
     timedOutNodes.sort();
     return { probes, timedOutNodes };
   }

package/src/runtime/foundation/service-mailbox.ts

@@ -1,13 +1,21 @@
 import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
 import type { ReceiveRecord } from './service-runtime-contracts';
+import type { RawServiceIngressRecord } from './raw-service-mesh-runtime';
 
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 
+export interface ServiceMailboxDispatchOwner {
+  prepareDispatch(record: ServiceMailboxRecord, signal: AbortSignal): boolean | Promise<boolean>;
+}
+
 export interface ServiceMailboxRecord {
+  readonly sourcePreparationOwner?: ServiceMailboxDispatchOwner;
+  readonly ingress?: RawServiceIngressRecord;
   readonly owner: string;
   readonly domain: ServiceMailboxDomain;
   parts: readonly Uint8Array[];
   readonly sourceRoutingId?: string;
+  readonly requestSource?: import('../locations/request-source-resolver').ZLinkRequestSourceFence;
   readonly sourceRoute?: Uint8Array;
   readonly requestSequence?: bigint;
   readonly reply?: (parts: readonly Uint8Array[]) => void;

package/src/runtime/foundation/service-maintenance-runtime.ts

@@ -1,7 +1,4 @@
-import { AsyncResource } from 'node:async_hooks';
-import { ZLinkStateLane } from '../execution/state-lane';
-
-const detachedStateLaneResource = new AsyncResource('zlink:service-maintenance-runtime');
+import { startOutsideStateLane, ZLinkStateLane } from '../execution/state-lane';
 
 export type ServiceMaintenanceKind = 'retire' | 'shutdown';
 export type ServiceMaintenanceState =
@@ -248,7 +245,3 @@ export class ServiceMaintenanceRuntime {
     for (const observer of publication.observers) observer(publication.snapshot);
   }
 }
-
-function startOutsideStateLane<T>(work: () => T): T {
-  return detachedStateLaneResource.runInAsyncScope(work);
-}

package/src/runtime/foundation/service-relocation-object-owner.ts

@@ -17,6 +17,7 @@ const DEFAULT_RELOCATION_CALLBACK_CONCURRENCY = 8;
 
 export interface ServiceRelocationSealedWork {
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: ServiceRelocationParticipant['sessionBinding'];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -29,7 +30,7 @@ export interface ServiceRelocationCaptureUnit {
   readonly authorityOwnerGeneration: bigint;
   seal(signal?: AbortSignal): Promise<ServiceRelocationSealedWork>;
   captureApplicationState(signal?: AbortSignal): Promise<Uint8Array>;
-  commitSeal(): Promise<void> | void;
+  commitSeal(followAuthorities: ReadonlyMap<string, ZLinkAuthoritySnapshot>): Promise<void> | void;
   abortSeal(): Promise<void> | void;
   /** Expired-owner terminal: pending requests fail once and dispatch stays closed. */
   discardSeal?(reason: unknown): Promise<void> | void;
@@ -43,12 +44,14 @@ export class ServiceCapturedObjectRelocation {
     private readonly units: readonly ServiceRelocationCaptureUnit[]
   ) {}
 
-  async commitSource(): Promise<void> {
+  async commitSource(
+    followAuthorities: ReadonlyMap<string, ZLinkAuthoritySnapshot>
+  ): Promise<void> {
     if (this.terminal === 'committed') return;
     if (this.terminal !== 'open') {
       throw new Error(`Relocation source capture was already ${this.terminal}.`);
     }
-    for (const unit of this.units) await unit.commitSeal();
+    for (const unit of this.units) await unit.commitSeal(followAuthorities);
     this.terminal = 'committed';
   }
 
@@ -57,17 +60,10 @@ export class ServiceCapturedObjectRelocation {
     if (this.terminal !== 'open') {
       throw new Error(`A ${this.terminal} relocation source capture cannot be aborted.`);
     }
-    const failures: unknown[] = [];
-    for (const unit of [...this.units].reverse()) {
-      try {
-        await unit.abortSeal();
-      } catch (error) {
-        failures.push(error);
-      }
-    }
-    this.terminal = 'aborted';
-    if (failures.length !== 0) {
-      throw new AggregateError(failures, 'Relocation source rollback was incomplete.');
+    try {
+      await abortSourceSeals(this.units);
+    } finally {
+      this.terminal = 'aborted';
     }
   }
 
@@ -166,31 +162,37 @@ export class ServiceRelocationObjectCaptureOwner {
   ): Promise<ServiceCapturedObjectRelocation> {
     const captured: Array<{
       readonly unit: ServiceRelocationCaptureUnit;
-      readonly work: ServiceRelocationSealedWork;
+      work?: ServiceRelocationSealedWork;
     }> = [];
     try {
       for (const unit of units) {
         signal?.throwIfAborted();
-        const work = await unit.seal(signal);
-        captured.push({ unit, work });
+        const capture: (typeof captured)[number] = { unit };
+        captured.push(capture);
+        capture.work = await unit.seal(signal);
       }
       const participants = await mapConcurrentOrdered(
         captured,
         this.maxConcurrentCallbacks,
-        async ({ unit, work }) => ({
-          key: unit.authorityKey,
-          objectKind: unit.objectKind,
-          stableType: unit.stableType,
-          objectGeneration: unit.objectGeneration,
-          authorityOwnerGeneration: unit.authorityOwnerGeneration,
-          applicationState: Buffer.from(await unit.captureApplicationState(signal)),
-          boundSessionState: Buffer.from(work.boundSessionState),
-          queuedMessages: work.queuedMessages.map((message) => ({
-            sequence: message.sequence,
-            payload: Buffer.from(message.payload)
-          })),
-          timers: work.timers.map((timer) => ({ ...timer }))
-        }),
+        async ({ unit, work: sealedWork }) => {
+          // Application capture starts only after every seal completed.
+          const work = sealedWork!;
+          return {
+            key: unit.authorityKey,
+            objectKind: unit.objectKind,
+            stableType: unit.stableType,
+            objectGeneration: unit.objectGeneration,
+            authorityOwnerGeneration: unit.authorityOwnerGeneration,
+            applicationState: Buffer.from(await unit.captureApplicationState(signal)),
+            boundSessionState: Buffer.from(work.boundSessionState),
+            ...(work.sessionBinding === undefined ? {} : { sessionBinding: work.sessionBinding }),
+            queuedMessages: work.queuedMessages.map((message) => ({
+              sequence: message.sequence,
+              payload: Buffer.from(message.payload)
+            })),
+            timers: work.timers.map((timer) => ({ ...timer }))
+          };
+        },
         signal
       );
       return new ServiceCapturedObjectRelocation(
@@ -203,12 +205,33 @@ export class ServiceRelocationObjectCaptureOwner {
         units
       );
     } catch (error) {
-      for (const { unit } of captured.reverse()) await unit.abortSeal();
+      try {
+        await abortSourceSeals(captured.map(({ unit }) => unit));
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          'Relocation capture failed and source rollback was incomplete.'
+        );
+      }
       throw error;
     }
   }
 }
 
+async function abortSourceSeals(units: readonly ServiceRelocationCaptureUnit[]): Promise<void> {
+  const failures: unknown[] = [];
+  for (const unit of [...units].reverse()) {
+    try {
+      await unit.abortSeal();
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures.length !== 0) {
+    throw new AggregateError(failures, 'Relocation source rollback was incomplete.');
+  }
+}
+
 export interface ServiceRelocationHiddenObject {
   readonly authorityKey: string;
 }
@@ -232,7 +255,6 @@ export interface ServiceRelocationTargetObjectPort<THidden extends ServiceReloca
     message: ServiceRelocationQueuedMessage,
     signal?: AbortSignal
   ): Promise<void>;
-  restoreTimer(hidden: THidden, timer: ServiceRelocationTimer, signal?: AbortSignal): Promise<void>;
   normalize(
     hidden: THidden,
     authority: ZLinkAuthoritySnapshot,
@@ -331,9 +353,6 @@ export class ServiceRelocationObjectRestoreOwner<
       for (const message of participant.queuedMessages) {
         await this.target.replayQueuedMessage(hidden, message, signal);
       }
-      for (const timer of participant.timers) {
-        await this.target.restoreTimer(hidden, timer, signal);
-      }
     }
   }
 

package/src/runtime/foundation/service-relocation-runtime.ts

@@ -39,6 +39,7 @@ export interface ServiceRelocationParticipant {
   readonly applicationStatePresent?: boolean;
   readonly applicationState: Uint8Array;
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: GeneratedRelocationEnvelopeV1['sessionBindings'][number];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -726,6 +727,11 @@ export function encodeServiceRelocationEnvelope(
           'timer due time'
         )
       })),
+      sessionBindings: participants.flatMap((participant, index) =>
+        participant.sessionBinding === undefined
+          ? []
+          : [{ ...participant.sessionBinding, participantId: BigInt(index + 1) }]
+      ),
       pendingTimerTicks: pending.map((value) => ({
         participantId: value.participantId,
         order: value.order,
@@ -765,11 +771,22 @@ export function decodeServiceRelocationEnvelope(
   const aggregateId = uuid(generated.relocationHigh, generated.relocationLow);
   if (aggregateId === undefined) throw new TypeError('Invalid relocation identity.');
   positiveBigInt(aggregateGeneration, 'aggregate generation');
+  const bindings = new Map(
+    generated.sessionBindings.map((binding) => [binding.participantId, binding])
+  );
+  for (const id of bindings.keys()) {
+    if (id > BigInt(generated.applicationStates.length))
+      throw new TypeError('Session binding participant is outside its inventory.');
+  }
   const participants = generated.applicationStates.map((state, index) => {
     if (state.participantId !== BigInt(index + 1)) {
       throw new TypeError('Application state participant order is invalid.');
     }
-    return wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload));
+    const binding = bindings.get(state.participantId);
+    return {
+      ...wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload)),
+      ...(binding === undefined ? {} : { sessionBinding: binding })
+    };
   });
   const byId = new Map(participants.map((value) => [value.participantId!, value]));
   for (const work of generated.savedWork) {
@@ -779,12 +796,16 @@ export function decodeServiceRelocationEnvelope(
     });
   }
   for (const timer of generated.timerRegistrations) {
+    const dueAtUnixMs = unixMilliseconds(timer.nextScheduledAtUnixMilliseconds);
+    const intervalMs = unixMilliseconds(timer.periodMilliseconds);
     byId.get(timer.participantId)!.timers.push({
       timerId: timer.name,
       handlerType: timer.handlerType,
-      startedAtUnixMs: 0,
-      dueAtUnixMs: unixMilliseconds(timer.nextScheduledAtUnixMilliseconds),
-      intervalMs: unixMilliseconds(timer.periodMilliseconds),
+      // The wire anchors the nominal schedule by its next due time: the next
+      // nominal tick after the completed ScheduledIndex (Spot timer §1).
+      startedAtUnixMs: dueAtUnixMs - Number(timer.lastCompletedScheduledIndex + 1n) * intervalMs,
+      dueAtUnixMs,
+      intervalMs,
       overrunPolicy: timerPolicyName(timer.overrunPolicy),
       maxCatchUpTicks: unixMilliseconds(timer.maxCatchUpTicks),
       stopOnUnhandledException: timer.stopOnUnhandledException,

package/src/runtime/foundation/service-runtime-contracts.ts

@@ -243,12 +243,22 @@ export interface ReceiveRequirements {
 }
 
 export interface ZLinkMessageFollowOrigin {
+  readonly requestSource?: import('../locations/request-source-resolver').ZLinkRequestSourceFence;
   readonly sourceNodeRid: RoutingId;
   readonly originalOperation: MeshOperationId;
   readonly originalReplyRouteId: bigint;
+  /** The canonical target accepted with the original native Actor frame. */
+  readonly target?: import('./service-stateful-wire-codec').ServiceActorRouteFence;
 }
 
 export interface ReceiveRecord {
+  /** Resolve record prerequisites in owner order, outside an application handler turn. */
+  readonly prepareDispatch?: (
+    this: ReceiveRecord,
+    signal: AbortSignal
+  ) => boolean | Promise<boolean>;
+  readonly statefulMailboxRecord?: import('./service-mailbox').ServiceMailboxRecord;
+  readonly requestSource?: import('../locations/request-source-resolver').ZLinkRequestSourceFence;
   readonly kind: number;
   readonly domain: number;
   readonly sourceNodeRid: RoutingId | null;
@@ -377,7 +387,8 @@ export interface StreamSessionService {
       retiredSession: ServiceRetiredBoundSessionRouteFence,
       actor: ServiceActorRef
     ) => void,
-    actorAuthority?: StreamSessionActorAuthorityFence
+    actorAuthority?: StreamSessionActorAuthorityFence,
+    close?: () => Promise<void>
   ): MeshOperationId;
   unbindActor(
     sessionRid: RoutingId,
@@ -422,7 +433,12 @@ export interface ServiceSpot {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendToSpot(
     targetNodeRid: unknown,
@@ -445,6 +461,7 @@ export interface ServiceSpot {
       timeoutMs?: number;
       applicationMetadata?: Buffer;
       routeFence?: ServiceDirectSpotRouteFence;
+      onAdmitted?: () => void;
       entrySpot?: boolean;
     }
   ): MeshOperationId;

package/src/runtime/foundation/service-session-binding-ingress-port.ts

@@ -1,5 +1,6 @@
+import type { RoutingId } from '../../contracts';
 export interface ServiceSessionBindingIngressPort {
-  actorSlot(actorId: string, sessionRid: string): Promise<number | undefined>;
+  actorSlot(actorId: string, sessionRid: RoutingId): Promise<number | undefined>;
 }
 
 const ports = new WeakMap<object, ServiceSessionBindingIngressPort>();

package/src/runtime/foundation/service-stateful-registry.ts

@@ -1,4 +1,9 @@
-import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
+import {
+  ZLINK_MAX_IDENTITY_TEXT_BYTES,
+  ZLINK_MAX_ROUTING_ID_BYTES
+} from '../../contracts/Common/CoreTypes';
+import { routingIdsEqual } from '../routing-id';
+import { encodeServiceWireRoutingId } from './service-wire-binary-primitives';
 import { OperationRegistry, type PendingOperation } from './operation-registry';
 
 export type ServiceSpotKind = 'entry' | 'user' | 'instance';
@@ -114,7 +119,6 @@ export class ServiceStatefulRegistry {
   private readonly reservationAttempts = new Map<string, bigint>();
   private readonly turns = new Map<string, Promise<void>>();
   private nextReservationId = 1n;
-  private nextBindingGeneration = 1n;
 
   constructor(
     readonly nodeRid: string,
@@ -392,47 +396,35 @@ export class ServiceStatefulRegistry {
     return current;
   }
 
-  bindSession(
-    actor: ServiceActorRef,
-    sessionRid: string,
-    sessionOwnerNodeRid: string,
-    sessionOwnerNodeGeneration?: bigint,
-    sessionOwnerId?: string,
-    sessionOwnerLeaseGeneration?: bigint
-  ): ServiceSessionBinding {
-    const current = this.requireActorCore(actor);
-    requireText(sessionRid, 'sessionRid');
-    requireText(sessionOwnerNodeRid, 'sessionOwnerNodeRid');
-    const binding: ServiceSessionBinding = Object.freeze({
-      actor: Object.freeze({ ...current.ref }),
-      sessionRid,
-      sessionOwnerNodeRid,
-      ...(sessionOwnerNodeGeneration === undefined ? {} : { sessionOwnerNodeGeneration }),
-      ...(sessionOwnerId === undefined ? {} : { sessionOwnerId }),
-      ...(sessionOwnerLeaseGeneration === undefined ? {} : { sessionOwnerLeaseGeneration }),
-      bindingGeneration: this.nextBindingGeneration++,
-      membershipEpoch: current.membershipEpoch
-    });
-    this.bindings.set(actorKey(actor), binding);
-    return binding;
-  }
-
-  installSessionBinding(binding: ServiceSessionBinding): void {
+  installSessionBinding(binding: ServiceSessionBinding): ServiceSessionBinding {
     this.requireActorCore(binding.actor);
+    encodeServiceWireRoutingId(
+      binding.sessionRid,
+      'sessionRid',
+      ZLINK_MAX_ROUTING_ID_BYTES,
+      (message) => {
+        throw new RangeError(message);
+      }
+    );
+    requireText(binding.sessionOwnerNodeRid, 'sessionOwnerNodeRid');
     requirePositive(binding.bindingGeneration, 'bindingGeneration');
     const current = this.bindings.get(actorKey(binding.actor));
     if (
       current !== undefined &&
       current.sessionOwnerNodeRid === binding.sessionOwnerNodeRid &&
       current.sessionOwnerNodeGeneration === binding.sessionOwnerNodeGeneration &&
-      current.sessionOwnerId === binding.sessionOwnerId &&
-      current.sessionOwnerLeaseGeneration === binding.sessionOwnerLeaseGeneration &&
       current.bindingGeneration >= binding.bindingGeneration
     ) {
+      if (
+        current.bindingGeneration === binding.bindingGeneration &&
+        current.sessionRid === binding.sessionRid
+      )
+        return current;
       throw new ServiceStaleGenerationError('binding', binding.actor.actorId);
     }
-    this.nextBindingGeneration = max(this.nextBindingGeneration, binding.bindingGeneration + 1n);
-    this.bindings.set(actorKey(binding.actor), Object.freeze({ ...binding }));
+    const accepted = Object.freeze({ ...binding });
+    this.bindings.set(actorKey(binding.actor), accepted);
+    return accepted;
   }
 
   binding(actor: ServiceActorRef): ServiceSessionBinding | undefined {
@@ -455,7 +447,8 @@ export class ServiceStatefulRegistry {
     if (binding === undefined) return false;
     if (
       binding.bindingGeneration !== expectedBindingGeneration ||
-      (expectedSessionRid !== undefined && binding.sessionRid !== expectedSessionRid) ||
+      (expectedSessionRid !== undefined &&
+        !routingIdsEqual(binding.sessionRid, expectedSessionRid)) ||
       (expectedSessionOwnerNodeRid !== undefined &&
         binding.sessionOwnerNodeRid !== expectedSessionOwnerNodeRid)
     ) {
@@ -621,6 +614,8 @@ function createSpotState(
   }
 }
 
+export const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
+
 export class ServiceTerminalOperationRegistry<T, Context = unknown> {
   private readonly operations: OperationRegistry<T, Context>;
 
@@ -636,8 +631,8 @@ export class ServiceTerminalOperationRegistry<T, Context = unknown> {
     return this.operations.register(timeoutMs, timeoutOwner, context);
   }
 
-  reply(id: bigint, value: T): boolean {
-    return this.operations.complete(id, value);
+  reply(id: bigint, value: T, terminalContextRetentionMs = 0): boolean {
+    return this.operations.complete(id, value, terminalContextRetentionMs);
   }
 
   fail(id: bigint, error: unknown): boolean {
@@ -660,6 +655,10 @@ export class ServiceTerminalOperationRegistry<T, Context = unknown> {
     return this.operations.size;
   }
 
+  nextDeadlineMs(): number {
+    return this.operations.nextDeadlineMs();
+  }
+
   expire(nowMs: number, turnDeadlineMs: number): number {
     return this.operations.expire(nowMs, turnDeadlineMs);
   }
@@ -667,6 +666,10 @@ export class ServiceTerminalOperationRegistry<T, Context = unknown> {
   close(): void {
     this.operations.close('Stateful runtime closed.');
   }
+
+  failAll(reason: unknown): void {
+    this.operations.failAll(reason);
+  }
 }
 
 function actorKey(actor: ServiceActorRef): string {