@zlink-systems/framework 0.28.0 → 0.29.0

package/src/runtime/host/instance-activation-authority.ts

@@ -16,7 +16,7 @@ import type {
   ZLinkAuthorityStore,
   ZLinkObjectCreationStore
 } from '../locations/internal-store-contracts';
-import { ZLinkFrameworkException } from '../../contracts';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
 import {
   decodeServiceInstanceAuthorityPayload,
   decodeServiceReadySpotAuthority,
@@ -46,7 +46,6 @@ import {
 
 const CREATION_REQUEST_RETENTION_MS = 24 * 60 * 60 * 1_000;
 const MAX_CREATION_REQUEST_BYTES = 1024 * 1024;
-const ACTIVATION_JOIN_POLL_INTERVAL_MS = 10;
 
 interface PendingReservation {
   readonly reservationId: string;
@@ -115,87 +114,81 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
     }
     let reserved: Awaited<ReturnType<ZLinkObjectCreationStore['reserve']>>;
     try {
-      for (;;) {
-        reserved = await this.options.store.reserve(
-          {
-            key: { kind: 'instance_spot', globalId: target.targetSpotId },
-            intent: {
-              stableType: target.stableType,
-              requestContentReference: stored.reference.value,
-              requestSha256: requestHash,
-              requestEncodedSize: BigInt(requestBytes.byteLength)
-            },
-            target: {
-              meshName: this.options.meshName,
-              nodeRid: target.targetNodeRid,
-              nodeLifecycleGeneration: target.targetNodeGeneration,
-              owner
-            },
-            creatingPayload: encodeServiceInstanceAuthorityPayload({
-              state: 'coldActivating',
+      reserved = await this.options.store.reserve(
+        {
+          key: { kind: 'instance_spot', globalId: target.targetSpotId },
+          intent: {
+            stableType: target.stableType,
+            requestContentReference: stored.reference.value,
+            requestSha256: requestHash,
+            requestEncodedSize: BigInt(requestBytes.byteLength)
+          },
+          target: {
+            meshName: this.options.meshName,
+            nodeRid: target.targetNodeRid,
+            nodeLifecycleGeneration: target.targetNodeGeneration,
+            owner
+          },
+          creatingPayload: encodeServiceInstanceAuthorityPayload({
+            state: 'coldActivating',
+            stableType: target.stableType,
+            spotId: target.targetSpotId,
+            ownerId: owner.ownerId,
+            ownerLeaseGeneration: owner.leaseGeneration,
+            ownerMeshName: this.options.meshName,
+            ownerNodeRid: target.targetNodeRid,
+            ownerNodeGeneration: target.targetNodeGeneration
+          }),
+          capacity: {
+            actors: 0,
+            spots: 1,
+            spotType: {
+              objectKind: 'instance_spot',
               stableType: target.stableType,
-              spotId: target.targetSpotId,
-              ownerId: owner.ownerId,
-              ownerLeaseGeneration: owner.leaseGeneration,
-              ownerMeshName: this.options.meshName,
-              ownerNodeRid: target.targetNodeRid,
-              ownerNodeGeneration: target.targetNodeGeneration
-            }),
-            capacity: {
-              actors: 0,
-              spots: 1,
-              spotType: {
-                objectKind: 'instance_spot',
-                stableType: target.stableType,
-                count: 1
-              }
+              count: 1
             }
-          },
-          undefined,
-          activation.deadlineUnixMs
-        );
-        if (reserved.kind !== 'alreadyExists') break;
-        this.options.metrics?.recordInstanceSpotClaimConflict(
-          this.options.meshName,
-          target.stableType,
-          'already_exists'
-        );
-        await this.deleteOrphan(stored.reference);
-        return readyExisting(reserved.current, target);
-      }
+          }
+        },
+        undefined,
+        activation.deadlineUnixMs
+      );
     } catch (error) {
       await this.deleteOrphan(stored.reference);
       throw error;
     }
-    if (
-      reserved.kind === 'conflict' &&
-      reserved.current.kind === 'snapshot' &&
-      reserved.current.allocation.objectKind === 'instance_spot' &&
-      reserved.current.allocation.stableType === target.stableType &&
-      reserved.current.allocation.state === 'reserved'
-    ) {
-      this.options.metrics?.recordInstanceSpotClaimConflict(
-        this.options.meshName,
-        target.stableType,
-        'activation_in_progress'
-      );
-      await this.deleteOrphan(stored.reference);
-      return await this.awaitConcurrentActivation(target, activation.deadlineUnixMs);
-    }
     if (reserved.kind !== 'reserved') {
+      const conflictReason =
+        reserved.kind === 'alreadyExists'
+          ? 'already_exists'
+          : reserved.kind === 'conflict' &&
+              reserved.current.kind === 'snapshot' &&
+              reserved.current.allocation.objectKind === 'instance_spot' &&
+              reserved.current.allocation.stableType === target.stableType &&
+              reserved.current.allocation.state === 'reserved'
+            ? 'activation_in_progress'
+            : reserved.kind;
       this.options.metrics?.recordInstanceSpotClaimConflict(
         this.options.meshName,
         target.stableType,
-        reserved.kind
+        conflictReason
       );
       await this.deleteOrphan(stored.reference);
+      if (reserved.kind === 'typeMismatch') {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotTypeMismatch,
+          `Instance activation reservation failed: ${reserved.kind}.`
+        );
+      }
       if (reserved.kind === 'placementCapacityExhausted') {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted,
           `Instance Spot placement capacity is exhausted for '${String(target.targetSpotId)}'.`
         );
       }
-      throw new Error(`Instance activation reservation failed: ${reserved.kind}.`);
+      throw new ZLinkFrameworkException(
+        ZLinkFrameworkErrorKind.Unavailable,
+        `Instance activation reservation failed: ${reserved.kind}.`
+      );
     }
     const reservation: ServiceInstanceActivationReservation = {
       attempt: reserved.creating.objectGeneration,
@@ -455,34 +448,6 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
     }
   }
 
-  private async awaitConcurrentActivation(
-    target: ServiceInstanceActivationTarget,
-    deadlineUnixMs: bigint
-  ): Promise<Extract<ServiceInstanceAuthorityRead, { readonly kind: 'ready' }>> {
-    const key = authorityKey(target.targetSpotId);
-    const deadlineMs = performance.now() + Number(deadlineUnixMs - BigInt(Date.now()));
-    while (performance.now() <= deadlineMs) {
-      const current = await this.options.store.readAuthority(key);
-      if (current.kind === 'snapshot') {
-        if (
-          current.allocation.objectKind !== 'instance_spot' ||
-          current.allocation.stableType !== target.stableType
-        ) {
-          throw new Error('Concurrent Instance activation resolved to a different Spot type.');
-        }
-        if (current.allocation.state === 'active') {
-          return readyExisting(current, target);
-        }
-      } else {
-        throw new Error('Concurrent Instance activation ended before the Ready barrier.');
-      }
-      await waitForActivationJoin(deadlineMs);
-    }
-    throw new Error(
-      `Concurrent Instance activation for '${target.targetSpotId}' did not reach Ready before deadline.`
-    );
-  }
-
   private requirePending(reservation: ServiceInstanceActivationReservation): PendingReservation {
     const pending = this.pending.get(reservation.token);
     if (pending === undefined || pending.creating.objectGeneration !== reservation.attempt) {
@@ -539,38 +504,6 @@ function readyRead(
   return { kind: 'ready', route: routeFromSnapshot(snapshot), authority: snapshot };
 }
 
-function readyExisting(
-  snapshot: ZLinkAuthoritySnapshot,
-  target: ServiceInstanceActivationTarget
-): Extract<ServiceInstanceAuthorityRead, { readonly kind: 'ready' }> {
-  const decoded =
-    decodeServiceReadySpotAuthority(snapshot.payload) ??
-    decodeServiceClosingSpotAuthority(snapshot.payload);
-  if (
-    decoded?.kind !== 'instance_spot' ||
-    decoded.stableType !== target.stableType ||
-    decoded.spotId !== target.targetSpotId ||
-    snapshot.allocation.objectKind !== 'instance_spot' ||
-    snapshot.allocation.state !== 'active' ||
-    decoded.ownerId !== snapshot.ownerId ||
-    decoded.ownerLeaseGeneration !== snapshot.ownerLeaseGeneration ||
-    decoded.ownerMeshName !== snapshot.allocation.descriptor.meshName ||
-    decoded.ownerNodeGeneration !== snapshot.allocation.descriptorLifecycleGeneration ||
-    !routingIdsEqual(decoded.ownerNodeRid, snapshot.allocation.descriptor.rid)
-  ) {
-    throw new Error('Existing Instance authority is not a matching Ready allocation.');
-  }
-  return { kind: 'ready', route: routeFromSnapshot(snapshot), authority: snapshot };
-}
-
-async function waitForActivationJoin(deadlineMs: number): Promise<void> {
-  const remaining = deadlineMs - performance.now();
-  if (remaining <= 0) return;
-  await new Promise<void>((resolve) => {
-    setTimeout(resolve, Math.min(ACTIVATION_JOIN_POLL_INTERVAL_MS, remaining));
-  });
-}
-
 function requireCommitIdentity(
   target: ServiceInstanceActivationTarget,
   reservation: ServiceInstanceActivationReservation,

package/src/runtime/host/spot-address-transport.ts

@@ -576,7 +576,7 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     if (stableType === undefined) {
       if (distinctTypes.length === 0) return { kind: 'unsupported' };
       throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.InvalidConfiguration,
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
         'Instance Spot type is required when multiple types are registered.'
       );
     }

package/src/runtime/host/stateful-authority-route-runtime.ts

@@ -1,3 +1,4 @@
+import { encodeAuthorityKey } from '../locations/authority-key-codec';
 import { createHash } from 'node:crypto';
 import type {
   ZLinkAuthorityKey,
@@ -175,12 +176,25 @@ export class ZLinkStatefulAuthorityRouteRuntime {
 
       const status = sink.status();
       for (const pending of snapshot.pending) {
+        if (pending.targetMeshName !== meshName) continue;
         if (
-          pending.targetMeshName === meshName &&
           routingIdsEqual(status.routingId, pending.targetNodeRid) &&
           status.lifecycleGeneration === pending.targetNodeGeneration
         ) {
           await this.recoverPendingInstanceActivation(sink, pending, signal);
+        } else {
+          const release = this.options.creationStore?.releaseEndedReservation;
+          if (release === undefined)
+            throw new Error('Reservation lifecycle recovery requires a Location repository.');
+          if (
+            await release.call(
+              this.options.creationStore,
+              encodeAuthorityKey('instance_spot', pending.spotId),
+              pending.pending.storeVersion,
+              signal
+            )
+          )
+            await this.clearRecoveryRoot(pending.pending.requestReference, signal);
         }
       }
 
@@ -386,14 +400,7 @@ export class ZLinkStatefulAuthorityRouteRuntime {
         signal
       );
       if (aborted.kind === 'aborted' || aborted.kind === 'alreadyAborted') {
-        try {
-          await this.options.relocationStore?.delete(
-            relocationBlobReference(recovery.pending.requestReference)
-          );
-        } catch {
-          // The authority no longer publishes this root. Retention owns a
-          // failed best-effort orphan cleanup.
-        }
+        await this.clearRecoveryRoot(recovery.pending.requestReference, signal);
       }
       return;
     }
@@ -401,6 +408,12 @@ export class ZLinkStatefulAuthorityRouteRuntime {
       return;
   }
 
+  private async clearRecoveryRoot(reference: string, signal?: AbortSignal): Promise<void> {
+    if (this.options.relocationStore === undefined)
+      throw new Error('Instance activation recovery requires a Relocation Store.');
+    await this.options.relocationStore.delete(relocationBlobReference(reference), signal);
+  }
+
   private async readRecoveryEnvelope(
     recovery: ServiceActivationRecoveryState,
     signal?: AbortSignal

package/src/runtime/locations/domain-store-contract.ts

@@ -140,6 +140,11 @@ export interface ZLinkDomainLocationStore {
     request: ZLinkObjectCreationCompleteRequest,
     signal?: AbortSignal
   ): Promise<ZLinkObjectCreationCompleteResult>;
+  releaseEndedReservation?(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal
+  ): Promise<boolean>;
   abort(
     request: ZLinkObjectAbortRequest,
     signal?: AbortSignal,

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

@@ -276,6 +276,42 @@ 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
+  ): boolean {
+    const current = this.rows.get(key.value);
+    if (
+      current === undefined ||
+      current.snapshot.storeVersion.value !== expectedStoreVersion ||
+      current.snapshot.allocation.state !== 'reserved' ||
+      current.creation === undefined ||
+      this.validation.isTargetLive(
+        current.snapshot.allocation.descriptor,
+        current.snapshot.allocation.descriptorLifecycleGeneration,
+        {
+          ownerId: current.snapshot.ownerId,
+          leaseGeneration: current.snapshot.ownerLeaseGeneration
+        }
+      )
+    )
+      return false;
+    this.adjustCapacity(this.pendingCapacity, current.snapshot.allocation, -1);
+    this.rows.delete(key.value);
+    this.creationTerminals.set(current.creation.reservationId, 'aborted');
+    this.scanRevision++;
+    return true;
+  }
+
   async reserve(
     request: ZLinkObjectReserveRequest,
     signal?: AbortSignal
@@ -297,15 +333,13 @@ export class ZLinkInMemoryAuthorityStore {
       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) {
+      if (
+        !this.tryReleaseEndedReservation(
+          encodeAuthorityKey(request.key.kind, request.key.globalId),
+          current.snapshot.storeVersion.value
+        )
+      )
         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++;
     }
     const target = creationTarget(request);
     if (

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

@@ -201,6 +201,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

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,77 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
     }
   }
 
+  override async releaseEndedReservation(
+    key: ZLinkAuthorityKey,
+    expectedStoreVersion: string,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    const rowKey = authorityKey(key.value);
+    const current = await this.provider.read(rowKey, signal);
+    if (current.kind === 'missing' || current.value.version.value !== expectedStoreVersion)
+      return false;
+    const record = decodeAuthorityRecord(current.value.bytes);
+    const snapshot = record.snapshot;
+    if (
+      snapshot.allocation.state !== 'reserved' ||
+      snapshot.pendingCreation === undefined ||
+      record.aggregate !== undefined ||
+      hasRelocationAuthority(snapshot.payload)
+    )
+      return false;
+    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.');
+    if (
+      sameLiveOwner(lease, snapshot) &&
+      descriptor.kind === 'found' &&
+      reviveMeshDescriptor(
+        decodeCanonicalDescriptorRecord<ZLinkMeshNodeDescriptor>(descriptor.value.bytes).descriptor
+      ).lifecycleGeneration === snapshot.allocation.descriptorLifecycleGeneration
+    )
+      return false;
+    const mutations: ZLinkStoreWriteRequest['mutations'][number][] = [
+      { kind: 'delete', key: rowKey }
+    ];
+    if (capacity.kind === 'found') {
+      const stored = decodeJson<CapacityRecord>(capacity.value.bytes);
+      mutations.push({
+        kind: 'put',
+        key: capacityRowKey,
+        bytes: encodeJson({
+          active: stored.active,
+          pending: subtractCapacity(stored.pending, snapshot.allocation.capacity)
+        } satisfies CapacityRecord)
+      });
+    }
+    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';
+  }
+
   override async reserve(
     request: ZLinkObjectReserveRequest,
     signal?: AbortSignal,
@@ -1130,62 +1227,13 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
           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.
-          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)) {
+          !(await this.releaseEndedReservation(
+            encodedAuthorityKey,
+            current.value.version.value,
+            signal
+          ))
+        )
           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
-        );
         continue;
       }
       const [descriptorRead, leaseRead] = await Promise.all([
@@ -4037,15 +4085,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 +4484,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-serial-executor.ts

@@ -134,7 +134,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;