@zlink-systems/framework 0.28.0 → 0.29.1

package/src/runtime/locations/in-memory-authority-store.ts

@@ -7,6 +7,7 @@ import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import { ZLINK_MAX_ROUTING_ID_BYTES } from '../../contracts/Common/CoreTypes';
 import { ZLINK_PROVIDER_MAX_PAGE_SIZE } from '../../contracts/Locations/Stores';
 import { randomUUID } from 'node:crypto';
+import { ZLinkFrameworkException, ZLinkFrameworkErrorKind } from '../../contracts';
 import { SHA256_DIGEST_BYTES } from '../foundation/actor-join-recovery-codec';
 import type {
   ZLinkAggregateAbortResult,
@@ -41,13 +42,16 @@ import type {
 } from './internal-location-contracts';
 import { encodeAuthorityKey } from './authority-key-codec';
 import { creationTerminalPreimage } from './opaque-record-key';
+import { ServiceRelocationAuthorityPayloadCodec } from '../foundation/service-relocation-runtime';
 
 const MAX_GENERATION = 0x7fff_ffff_ffff_ffffn;
 
 const CREATION_TERMINAL_RETENTION_MS = 5 * 60 * 1000;
 const MAX_U64 = UINT64_MAX;
+const relocationAuthorityCodec = new ServiceRelocationAuthorityPayloadCodec();
 
 export interface ZLinkInMemoryAuthorityValidation {
+  isOwnerLive(owner: ZLinkLocationOwnerToken): boolean;
   isTargetLive(
     descriptor: ZLinkMeshNodeDescriptorKey,
     lifecycleGeneration: bigint,
@@ -276,6 +280,75 @@ export class ZLinkInMemoryAuthorityStore {
     return BigInt(removed);
   }
 
+  async releaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    signal?.throwIfAborted();
+    return this.tryReleaseEndedReservation(key, expectedStoreVersion);
+  }
+
+  private tryReleaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    request?: ZLinkObjectReserveRequest
+  ): boolean {
+    const current = this.rows.get(key.value);
+    if (
+      current === undefined ||
+      current.snapshot.storeVersion.value !== expectedStoreVersion ||
+      (current.snapshot.allocation.state === 'active'
+        ? request?.key.kind !== 'actor'
+        : current.creation === undefined)
+    )
+      return false;
+    if (current.snapshot.allocation.state === 'active') {
+      for (const aggregate of this.aggregates.values()) {
+        if (
+          aggregate.state === 'prepared' &&
+          aggregate.request.participants.some(
+            (participant) => participant.authorityKey.value === key.value
+          )
+        )
+          return false;
+      }
+      if (relocationAuthorityCodec.read(current.snapshot.payload) !== undefined) return false;
+      if (
+        this.validation.isOwnerLive({
+          ownerId: current.snapshot.ownerId,
+          leaseGeneration: current.snapshot.ownerLeaseGeneration
+        })
+      )
+        return false;
+      if (request?.actorRelocationPolicy !== 'disabled')
+        throw new ZLinkFrameworkException(
+          ZLinkFrameworkErrorKind.Unavailable,
+          'Actor owner lease is unavailable.'
+        );
+    } else if (
+      this.validation.isTargetLive(
+        current.snapshot.allocation.descriptor,
+        current.snapshot.allocation.descriptorLifecycleGeneration,
+        {
+          ownerId: current.snapshot.ownerId,
+          leaseGeneration: current.snapshot.ownerLeaseGeneration
+        }
+      )
+    )
+      return false;
+    this.adjustCapacity(
+      current.snapshot.allocation.state === 'active' ? this.activeCapacity : this.pendingCapacity,
+      current.snapshot.allocation,
+      -1
+    );
+    this.rows.delete(key.value);
+    if (current.snapshot.allocation.state === 'reserved' && current.creation !== undefined)
+      this.creationTerminals.set(current.creation.reservationId, 'aborted');
+    this.scanRevision++;
+    return true;
+  }
+
   async reserve(
     request: ZLinkObjectReserveRequest,
     signal?: AbortSignal
@@ -294,18 +367,16 @@ export class ZLinkInMemoryAuthorityStore {
       ) {
         return { kind: 'typeMismatch', current: this.snapshot(current.snapshot) };
       }
-      if (current.snapshot.allocation.state === 'active') {
-        return { kind: 'alreadyExists', current: this.snapshot(current.snapshot) };
-      }
-      // An unfinished creation whose owner lease ended is cancellable.
-      // Reclaim it so the key does not stay blocked forever.
-      if (this.isOwnerLive(current.snapshot) || current.creation === undefined) {
-        return { kind: 'conflict', current: this.read(key) };
-      }
-      this.adjustCapacity(this.pendingCapacity, current.snapshot.allocation, -1);
-      this.rows.delete(key);
-      this.creationTerminals.set(current.creation.reservationId, 'aborted');
-      this.scanRevision++;
+      if (
+        !this.tryReleaseEndedReservation(
+          encodeAuthorityKey(request.key.kind, request.key.globalId),
+          current.snapshot.storeVersion.value,
+          request
+        )
+      )
+        return current.snapshot.allocation.state === 'active'
+          ? { kind: 'alreadyExists', current: this.snapshot(current.snapshot) }
+          : { kind: 'conflict', current: this.read(key) };
     }
     const target = creationTarget(request);
     if (

package/src/runtime/locations/in-memory-location-store.ts

@@ -99,11 +99,14 @@ export class ZLinkInMemoryLocationStore
   private readonly authority: ZLinkInMemoryAuthorityStore;
 
   constructor(private readonly now: () => Date = () => new Date()) {
+    const isOwnerLive = (owner: ZLinkLocationOwnerToken): boolean =>
+      this.liveOwnerLease(owner.ownerId, this.now())?.token.leaseGeneration ===
+      owner.leaseGeneration;
     this.authority = new ZLinkInMemoryAuthorityStore(
       {
+        isOwnerLive,
         isTargetLive: (key, lifecycleGeneration, owner) => {
           const descriptor = this.meshNodes.rows.get(meshNodeKey(key.meshName, key.rid));
-          const lease = this.leases.get(owner.ownerId);
           return (
             descriptor !== undefined &&
             descriptor.lifecycleGeneration === lifecycleGeneration &&
@@ -111,9 +114,7 @@ export class ZLinkInMemoryLocationStore
             descriptor.leaseGeneration === owner.leaseGeneration &&
             descriptor.objectRole === ZLinkObjectRole.Server &&
             descriptor.state === ZLinkFrameworkRuntimeState.Serving &&
-            lease !== undefined &&
-            lease.token.leaseGeneration === owner.leaseGeneration &&
-            lease.leaseExpiresAt.getTime() > this.now().getTime()
+            isOwnerLive(owner)
           );
         },
         placementCapacityAvailable: (key, requested, reserved, active) => {
@@ -201,6 +202,14 @@ export class ZLinkInMemoryLocationStore
     return this.authority.readCreationTerminal(operation, signal);
   }
 
+  async releaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    return this.authority.releaseEndedReservation(key, expectedStoreVersion, signal);
+  }
+
   async abort(
     request: ZLinkObjectAbortRequest,
     signal?: AbortSignal
@@ -558,7 +567,8 @@ export class ZLinkInMemoryLocationStore
     const storeNow = this.now();
     return pageRows(
       this.fanoutPublishers,
-      (row) => row.channelName === channelName && this.isOwnerLive(row.ownerId, storeNow),
+      (row) =>
+        row.channelName === channelName && this.liveOwnerLease(row.ownerId, storeNow) !== undefined,
       page
     );
   }
@@ -620,7 +630,7 @@ export class ZLinkInMemoryLocationStore
     if (
       intent === ZLinkLocationWriteIntent.NewClaim &&
       current !== undefined &&
-      this.isOwnerLive(current.ownerId, updatedAt)
+      this.liveOwnerLease(current.ownerId, updatedAt) !== undefined
     ) {
       return rejectedConflict();
     }
@@ -698,7 +708,7 @@ export class ZLinkInMemoryLocationStore
     if (
       intent === ZLinkLocationWriteIntent.NewClaim &&
       current !== undefined &&
-      this.isOwnerLive(current.ownerId, updatedAt)
+      this.liveOwnerLease(current.ownerId, updatedAt) !== undefined
     ) {
       return rejectedConflict();
     }
@@ -1147,7 +1157,7 @@ export class ZLinkInMemoryLocationStore
     if (
       intent === ZLinkLocationWriteIntent.NewClaim &&
       current !== undefined &&
-      this.isOwnerLive(ownerOf(current), updatedAt)
+      this.liveOwnerLease(ownerOf(current), updatedAt) !== undefined
     ) {
       return rejectedConflict();
     }
@@ -1244,9 +1254,11 @@ export class ZLinkInMemoryLocationStore
     return removed;
   }
 
-  private isOwnerLive(ownerId: string, now: Date): boolean {
+  private liveOwnerLease(ownerId: string, now: Date): InMemoryOwnerLease | undefined {
     const lease = this.leases.get(ownerId);
-    return lease !== undefined && lease.leaseExpiresAt.getTime() > now.getTime();
+    return lease !== undefined && lease.leaseExpiresAt.getTime() > now.getTime()
+      ? lease
+      : undefined;
   }
 
   private bump(kind: ZLinkLocationKind, meshName: string | undefined): void {

package/src/runtime/locations/internal-location-contracts.ts

@@ -1,4 +1,10 @@
 export * from '../../contracts/Locations';
+import type { ZLinkObjectReserveRequest as ReserveRequest } from '../../contracts/Locations/Authority';
+import type { ZLinkRelocationConfiguration } from '../../contracts/Configuration/RegistrationTypes';
+
+export interface ZLinkObjectReserveRequest extends ReserveRequest {
+  readonly actorRelocationPolicy?: ZLinkRelocationConfiguration<unknown>['kind'];
+}
 export type * from '../../contracts/Locations/Authority';
 export type {
   ZLinkActorLocation,

package/src/runtime/locations/internal-store-contracts.ts

@@ -32,6 +32,7 @@ export type ZLinkObjectCreationStore = Pick<
   | 'commit'
   | 'completeCreation'
   | 'abort'
+  | 'releaseEndedReservation'
   | 'prepareAggregate'
   | 'commitAggregate'
   | 'abortAggregate'

package/src/runtime/locations/location-store-repository.ts

@@ -1,3 +1,4 @@
+import { ServiceRelocationAuthorityPayloadCodec } from '../foundation/service-relocation-runtime';
 import { UINT64_MAX } from '@zlink-systems/stream-wire';
 import { createHash, randomUUID } from 'node:crypto';
 import { zlinkRuntimeDefaultLocationOptions } from '../../contracts/Locations/Options';
@@ -17,6 +18,8 @@ import {
   type ZLinkStoreScanCursor,
   type ZLinkStoreVersion,
   type ZLinkStoreWriteRequest,
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind,
   ZLinkFrameworkRuntimeState,
   ZLinkObjectRole
 } from '../../contracts';
@@ -204,7 +207,30 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
     private readonly nowProvider: () => Date = () => new Date()
   ) {
     super(nowProvider);
-    this.provider = provider;
+    // Classify only failures of the opaque SPI, before interpreting its records.
+    this.provider = {
+      async read(key, signal) {
+        try {
+          return await provider.read(key, signal);
+        } catch (error) {
+          throw locationStoreProviderFailure(error, signal);
+        }
+      },
+      async write(request, signal) {
+        try {
+          return await provider.write(request, signal);
+        } catch (error) {
+          throw locationStoreProviderFailure(error, signal);
+        }
+      },
+      async scan(request, signal) {
+        try {
+          return await provider.scan(request, signal);
+        } catch (error) {
+          throw locationStoreProviderFailure(error, signal);
+        }
+      }
+    };
     this.aggregateInventory = new ZLinkAggregateInventoryStore(this.provider);
   }
 
@@ -1099,6 +1125,118 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
     }
   }
 
+  override async releaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    return (
+      (await this.tryReleaseEndedReservation(key, expectedStoreVersion, signal)) === 'reclaimed'
+    );
+  }
+
+  private async tryReleaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal,
+    request?: ZLinkObjectReserveRequest
+  ): Promise<'notReclaimable' | 'conflict' | 'reclaimed'> {
+    const rowKey = authorityKey(key.value);
+    const current = await this.provider.read(rowKey, signal);
+    if (current.kind === 'missing' || current.value.version.value !== expectedStoreVersion)
+      return 'conflict';
+    const record = decodeAuthorityRecord(current.value.bytes);
+    const snapshot = record.snapshot;
+    if (
+      (snapshot.allocation.state === 'active'
+        ? request?.key.kind !== 'actor'
+        : snapshot.pendingCreation === undefined) ||
+      record.aggregate !== undefined ||
+      hasRelocationAuthority(snapshot.payload)
+    )
+      return 'notReclaimable';
+    const leaseKey = ownerKey(snapshot.ownerId);
+    const descriptorKey = meshKey(
+      snapshot.allocation.descriptor.meshName,
+      snapshot.allocation.descriptor.rid
+    );
+    const capacityRowKey = capacityKey(
+      snapshot.allocation.descriptor.meshName,
+      String(snapshot.allocation.descriptor.rid)
+    );
+    const [lease, descriptor, capacity] = await Promise.all([
+      this.provider.read(leaseKey, signal),
+      this.provider.read(descriptorKey, signal),
+      this.provider.read(capacityRowKey, signal)
+    ]);
+    if (lease.kind === 'found' && lease.value.expiresAt === undefined)
+      throw new Error('Location Store owner lease record is invalid.');
+    const ownerLive = sameLiveOwner(lease, snapshot);
+    if (snapshot.allocation.state === 'active') {
+      if (ownerLive) return 'notReclaimable';
+      if (request?.actorRelocationPolicy !== 'disabled')
+        throw new ZLinkFrameworkException(
+          ZLinkFrameworkErrorKind.Unavailable,
+          'Actor owner lease is unavailable.'
+        );
+    } else if (
+      ownerLive &&
+      descriptor.kind === 'found' &&
+      reviveMeshDescriptor(
+        decodeCanonicalDescriptorRecord<ZLinkMeshNodeDescriptor>(descriptor.value.bytes).descriptor
+      ).lifecycleGeneration === snapshot.allocation.descriptorLifecycleGeneration
+    )
+      return 'notReclaimable';
+    const mutations: ZLinkStoreWriteRequest['mutations'][number][] = [
+      { kind: 'delete', key: rowKey }
+    ];
+    if (capacity.kind === 'found') {
+      const stored = decodeJson<CapacityRecord>(capacity.value.bytes);
+      try {
+        mutations.push({
+          kind: 'put',
+          key: capacityRowKey,
+          bytes: encodeJson({
+            active:
+              snapshot.allocation.state === 'active'
+                ? subtractCapacity(stored.active, snapshot.allocation.capacity)
+                : stored.active,
+            pending:
+              snapshot.allocation.state === 'reserved'
+                ? subtractCapacity(stored.pending, snapshot.allocation.capacity)
+                : stored.pending
+          } satisfies CapacityRecord)
+        });
+      } catch (error) {
+        if (
+          !(error instanceof ZLinkFrameworkException) ||
+          error.kind !== ZLinkFrameworkErrorKind.DataLost
+        )
+          throw error;
+        const observed = await this.provider.read(rowKey, signal);
+        if (
+          observed.kind === 'missing' ||
+          observed.value.version.value !== current.value.version.value
+        )
+          return 'conflict';
+        throw error;
+      }
+    }
+    const result = await this.provider.write(
+      {
+        conditions: [
+          { kind: 'version', key: rowKey, expected: current.value.version },
+          conditionFor(leaseKey, lease),
+          conditionFor(descriptorKey, descriptor),
+          conditionFor(capacityRowKey, capacity)
+        ],
+        mutations
+      },
+      signal
+    );
+    return result.kind === 'applied' ? 'reclaimed' : 'conflict';
+  }
+
   override async reserve(
     request: ZLinkObjectReserveRequest,
     signal?: AbortSignal,
@@ -1106,6 +1244,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
   ): Promise<ZLinkObjectReserveResult> {
     const encodedAuthorityKey = encodeAuthorityKey(request.key.kind, request.key.globalId);
     const reservationId = randomUUID();
+    let reclaimVersion: string | undefined;
     for (;;) {
       throwIfOperationExpired(signal, deadlineUnixMs);
       const rowKey = authorityKey(encodedAuthorityKey.value);
@@ -1126,68 +1265,23 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         ) {
           return { kind: 'typeMismatch', current: snapshot };
         }
-        if (snapshot.allocation.state === 'active') {
-          return { kind: 'alreadyExists', current: snapshot };
-        }
-        if (
-          record.aggregate !== undefined ||
-          isCanonicalAuthorityPayload(record.snapshot.payload)
-        ) {
-          // A relocation record carries its own recovery protocol. Reserve
-          // may reclaim only an unfinished plain creation.
+        if (reclaimVersion !== undefined && snapshot.storeVersion.value !== reclaimVersion)
           return { kind: 'conflict', current: snapshot };
-        }
-        // The row is Reserved by another owner. An unfinished creation
-        // whose owner lease ended is cancellable, so reclaim it and retry
-        // instead of blocking the key forever.
-        const staleOwnerKey = ownerKey(snapshot.ownerId);
-        const staleCapacityKey = capacityKey(
-          snapshot.allocation.descriptor.meshName,
-          String(snapshot.allocation.descriptor.rid)
-        );
-        const [staleOwnerRead, staleCapacityRead] = await Promise.all([
-          this.provider.read(staleOwnerKey, signal),
-          this.provider.read(staleCapacityKey, signal)
-        ]);
-        if (staleOwnerRead.kind === 'found' && staleOwnerRead.value.expiresAt === undefined) {
-          // A lease is always written with a positive TTL, so a missing
-          // expiry is a corrupt record. Reclaiming deletes authority state,
-          // so refuse rather than read the absence as expiry.
-          throw new Error('Location Store owner lease record is invalid.');
-        }
-        if (sameLiveOwner(staleOwnerRead, record.snapshot)) {
-          return { kind: 'conflict', current: snapshot };
-        }
-        const staleCapacity =
-          staleCapacityRead.kind === 'missing'
-            ? emptyCapacityRecord()
-            : decodeJson<CapacityRecord>(staleCapacityRead.value.bytes);
-        await this.provider.write(
-          {
-            conditions: [
-              { kind: 'version', key: rowKey, expected: current.value.version },
-              versionCondition(staleOwnerKey, staleOwnerRead),
-              conditionFor(staleCapacityKey, staleCapacityRead)
-            ],
-            mutations: [
-              { kind: 'delete', key: rowKey },
-              {
-                kind: 'put',
-                key: staleCapacityKey,
-                bytes: encodeJson({
-                  active: staleCapacity.active,
-                  pending: subtractCapacity(
-                    staleCapacity.pending,
-                    record.snapshot.allocation.capacity
-                  )
-                } satisfies CapacityRecord)
-              }
-            ]
-          },
-          signal
+        const reclaim = await this.tryReleaseEndedReservation(
+          encodedAuthorityKey,
+          current.value.version.value,
+          signal,
+          request
         );
+        if (reclaim === 'notReclaimable')
+          return snapshot.allocation.state === 'active'
+            ? { kind: 'alreadyExists', current: snapshot }
+            : { kind: 'conflict', current: snapshot };
+        reclaimVersion = reclaim === 'conflict' ? snapshot.storeVersion.value : undefined;
         continue;
       }
+      if (reclaimVersion !== undefined)
+        return { kind: 'conflict', current: { kind: 'missing', storeNow: current.storeNow } };
       const [descriptorRead, leaseRead] = await Promise.all([
         this.provider.read(descriptorKey, signal),
         this.provider.read(leaseKey, signal)
@@ -3992,13 +4086,21 @@ function adjustCapacity(
   if (delta.spotType !== undefined) {
     const key = capacityTypeKey(delta.spotType);
     const next = (spotTypes[key] ?? 0) + direction * delta.spotType.count;
-    if (next < 0) throw new Error('Provider capacity counter underflow.');
+    if (next < 0)
+      throw new ZLinkFrameworkException(
+        ZLinkFrameworkErrorKind.DataLost,
+        'Provider capacity counter underflow.'
+      );
     if (next === 0) delete spotTypes[key];
     else spotTypes[key] = next;
   }
   const actors = usage.actors + direction * delta.actors;
   const spots = usage.spots + direction * delta.spots;
-  if (actors < 0 || spots < 0) throw new Error('Provider capacity counter underflow.');
+  if (actors < 0 || spots < 0)
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.DataLost,
+      'Provider capacity counter underflow.'
+    );
   return { actors, spots, spotTypes };
 }
 
@@ -4037,15 +4139,10 @@ function sameCreationTarget(
   );
 }
 
-const CANONICAL_AUTHORITY_MAGIC = Buffer.from('ZLAU');
+const relocationAuthorityCodec = new ServiceRelocationAuthorityPayloadCodec();
 
-function isCanonicalAuthorityPayload(payload: Uint8Array): boolean {
-  return (
-    payload.byteLength >= CANONICAL_AUTHORITY_MAGIC.byteLength &&
-    Buffer.from(payload.buffer, payload.byteOffset, CANONICAL_AUTHORITY_MAGIC.byteLength).equals(
-      CANONICAL_AUTHORITY_MAGIC
-    )
-  );
+function hasRelocationAuthority(payload: Uint8Array): boolean {
+  return relocationAuthorityCodec.read(payload) !== undefined;
 }
 
 function sameLiveOwner(lease: ZLinkStoreReadResult, snapshot: StoredAuthoritySnapshot): boolean {
@@ -4441,3 +4538,19 @@ function throwIfOperationExpired(signal?: AbortSignal, deadlineUnixMs?: bigint):
     throw new DOMException('Operation deadline exceeded.', 'TimeoutError');
   }
 }
+
+// Store SPI §6: preserve caller failures and classify provider failures once.
+function locationStoreProviderFailure(error: unknown, signal?: AbortSignal): unknown {
+  if (
+    error instanceof ZLinkFrameworkException ||
+    error instanceof TypeError ||
+    error instanceof RangeError ||
+    signal?.aborted === true
+  )
+    return error;
+  return new ZLinkFrameworkException(
+    ZLinkFrameworkErrorKind.Unavailable,
+    'Location Store provider is unavailable.',
+    error
+  );
+}

package/src/runtime/protocol/service_wire_pilot_codec.generated.ts

@@ -1,4 +1,4 @@
-// <auto-generated> DO NOT EDIT. schema-sha256: 77748ba8f585cb70ad337fa3203b5f9b9aa7a89e7f95f7fdc20159c30987be0f
+// <auto-generated> DO NOT EDIT. schema-sha256: 818fcd2f767793be8b5f626e5ac688807e671e546af2b11786e6fbaa02010ba5
 export interface ServiceWireRouteFence { readonly id: string; readonly generation: bigint; readonly targetNodeRid: Uint8Array; readonly targetNodeGeneration: bigint; readonly expectedAuthorityOwnerGeneration: bigint; readonly expectedOwnerLeaseGeneration: bigint; }
 	export interface ApplicationPayloadEnvelopeV1 { readonly packetName: string; readonly contentType: string; readonly payload: Uint8Array; }
 	export interface ActorJoin28 { readonly correlation: bigint; readonly actor: ServiceWireRouteFence; readonly entry: boolean; readonly targetSpot: ServiceWireRouteFence; readonly payload?: ApplicationPayloadEnvelopeV1; }

package/src/runtime/spots/spot-entry-activation.ts

@@ -378,6 +378,10 @@ export class ZLinkEntrySpotActivation {
     return this.spotSerialExecutor.executeActor(actorId, operation);
   }
 
+  terminateActor(actorId: string, terminal: () => Promise<void>): Promise<void> {
+    return this.spotSerialExecutor.terminateActor(actorId, terminal);
+  }
+
   /**
    * Entry Spot membership does not have an application admission callback.
    * The shared core round-trip therefore accepts a valid returning Actor and

package/src/runtime/spots/spot-node-runtime-manager.ts

@@ -783,6 +783,13 @@ export class ZLinkSpotNodeRuntimeManager {
     return activation?.notifyJoinActor(actor, signal) ?? Promise.resolve();
   }
 
+  terminateActorActivation(actor: ZLinkActor, terminal: () => Promise<void>): Promise<void> {
+    const activation = this.entryActivations.get(actor.context.meshName);
+    return activation === undefined
+      ? terminal()
+      : activation.terminateActor(actor.context.actorId, terminal);
+  }
+
   notifyPrimaryEntrySpotActorLeft(
     actor: ZLinkActor,
     signal?: AbortSignal,

package/src/runtime/spots/spot-serial-executor.ts

@@ -51,10 +51,8 @@ export class ZLinkSpotSerialExecutor {
     operation: (serial: ZLinkSpotSerialTurnExecutor) => Promise<T> | T,
     workOptions?: ZLinkSerialWorkOptions
   ): Promise<T> {
-    return this.actorExecutor(actorId).execute(
-      () => operation(this.actorSerial(actorId)),
-      workOptions
-    );
+    const serial = this.actorSerial(actorId);
+    return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
   }
 
   /** @internal Restores a durable Actor FIFO prefix without starting it. */
@@ -102,6 +100,14 @@ export class ZLinkSpotSerialExecutor {
     return this.spotSerial.execute(operation, { ...workOptions, lane: 'lifecycle' });
   }
 
+  async terminateActor(actorId: string, terminal: () => Promise<void>): Promise<void> {
+    const executor = this.actorExecutor(actorId);
+    await executor.close();
+    await terminal();
+    if (this.actorExecutors.get(actorId) === executor) this.actorExecutors.delete(actorId);
+    this.actorSerials.delete(actorId);
+  }
+
   /**
    * Makes all child queues unreachable and completes them in one synchronous
    * ownership turn. Already accepted work remains drainable.
@@ -134,7 +140,10 @@ export class ZLinkSpotSerialExecutor {
     this.throwIfClosing();
     let executor = this.actorExecutors.get(actorId);
     if (executor === undefined) {
-      executor = new ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
+      executor =
+        this.executionMode === ZLinkUserSpotExecutionMode.SpotWide
+          ? this.spotSerial.createActorExecutor(actorId, this.sourceSpotId, this.actorOptions)
+          : new ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
       this.actorExecutors.set(actorId, executor);
     }
     return executor;

package/src/runtime/spots/spot-serial-turn-executor.ts

@@ -19,6 +19,7 @@ import {
   type ZLinkSerialWorkRecord
 } from '../execution/serial-execution-queue';
 import type { ZLinkSerialLifecycleContext } from '../execution/serial-execution-queue';
+import { ZLinkActorSerialExecutor } from '../actors/actor-mailbox';
 
 export type ZLinkSpotApplicationTurnContext = ZLinkExecutionBarrierClaim & {
   readonly replay?: (failure?: unknown) => Promise<unknown> | unknown;
@@ -53,6 +54,15 @@ export class ZLinkSpotSerialTurnExecutor {
     return this.depth > 0;
   }
 
+  /** Creates a passive Actor mailbox consumed by this Spot's scheduler. */
+  createActorExecutor(
+    actorId: string,
+    sourceSpotId: unknown,
+    options?: ZLinkSerialSchedulerOptions
+  ): ZLinkActorSerialExecutor {
+    return new ZLinkActorSerialExecutor(actorId, sourceSpotId, options, this.scheduler);
+  }
+
   get isCurrentTurn(): boolean {
     return this.depth > 0 && isCurrentZLinkSpotSerialTurn(this);
   }

package/src/runtime/streams/index.ts

@@ -87,7 +87,6 @@ import {
   type ZLinkStreamSessionRuntimeOptions as ZLinkStreamSessionRuntimeCoreOptions
 } from './stream-session-runtime';
 const DEFAULT_STREAM_SERVICE_SHUTDOWN_TIMEOUT_MS = 1000;
-export { ZLinkPendingSessionRequest } from './session-requests';
 export { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 export { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
 export { zlinkStreamLz4CompressionCodec } from './stream-frame-factory';
@@ -305,6 +304,9 @@ export class ZLinkStreamRuntimeManager {
       const readablePoller = streamAdapter.createReadablePoller(socket);
       const runtime = new ZLinkStreamSessionNodeRuntimeCore({
         nodeName,
+        heartbeatIntervalMs: streamNode.heartbeatIntervalMs,
+        heartbeatTimeoutMs: streamNode.heartbeatTimeoutMs,
+        idleTimeoutMs: streamNode.idleTimeoutMs,
         socket,
         createPacket: () => streamAdapter.createStreamPacket(),
         readablePoller,