@zlink-systems/framework 0.30.1 → 0.30.2

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

@@ -30,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;
@@ -44,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';
   }
 
@@ -58,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';
     }
   }
 
@@ -167,32 +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),
-          ...(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 }))
-        }),
+        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(
@@ -205,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;
 }
@@ -234,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,
@@ -333,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

@@ -796,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,

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 {