@zlink-systems/framework 0.28.0 → 0.29.0

package/dist/runtime/host/instance-activation-authority.js

@@ -11,7 +11,6 @@ const relocation_blob_1 = require("../locations/relocation-blob");
 const service_instance_activation_recovery_codec_1 = require("../foundation/service-instance-activation-recovery-codec");
 const CREATION_REQUEST_RETENTION_MS = 24 * 60 * 60 * 1_000;
 const MAX_CREATION_REQUEST_BYTES = 1024 * 1024;
-const ACTIVATION_JOIN_POLL_INTERVAL_MS = 10;
 class ZLinkInstanceActivationAuthority {
     options;
     pending = new Map();
@@ -48,68 +47,64 @@ class ZLinkInstanceActivationAuthority {
         }
         let reserved;
         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: (0, service_authority_payload_codec_1.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: (0, service_authority_payload_codec_1.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') {
-            this.options.metrics?.recordInstanceSpotClaimConflict(this.options.meshName, target.stableType, reserved.kind);
+            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, conflictReason);
             await this.deleteOrphan(stored.reference);
+            if (reserved.kind === 'typeMismatch') {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch, `Instance activation reservation failed: ${reserved.kind}.`);
+            }
             if (reserved.kind === 'placementCapacityExhausted') {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `Instance Spot placement capacity is exhausted for '${String(target.targetSpotId)}'.`);
             }
-            throw new Error(`Instance activation reservation failed: ${reserved.kind}.`);
+            throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.Unavailable, `Instance activation reservation failed: ${reserved.kind}.`);
         }
         const reservation = {
             attempt: reserved.creating.objectGeneration,
@@ -334,27 +329,6 @@ class ZLinkInstanceActivationAuthority {
             // best-effort deletion fails.
         }
     }
-    async awaitConcurrentActivation(target, deadlineUnixMs) {
-        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.`);
-    }
     requirePending(reservation) {
         const pending = this.pending.get(reservation.token);
         if (pending === undefined || pending.creating.objectGeneration !== reservation.attempt) {
@@ -402,31 +376,6 @@ function readyRead(snapshot, target) {
     }
     return { kind: 'ready', route: routeFromSnapshot(snapshot), authority: snapshot };
 }
-function readyExisting(snapshot, target) {
-    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload) ??
-        (0, service_authority_payload_codec_1.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 ||
-        !(0, routing_id_1.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) {
-    const remaining = deadlineMs - performance.now();
-    if (remaining <= 0)
-        return;
-    await new Promise((resolve) => {
-        setTimeout(resolve, Math.min(ACTIVATION_JOIN_POLL_INTERVAL_MS, remaining));
-    });
-}
 function requireCommitIdentity(target, reservation, creating, spot, meshName) {
     if (creating.allocation.state !== 'reserved' ||
         creating.allocation.objectKind !== 'instance_spot' ||

package/dist/runtime/host/spot-address-transport.js

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

package/dist/runtime/host/stateful-authority-route-runtime.d.ts

@@ -28,6 +28,7 @@ export declare class ZLinkStatefulAuthorityRouteRuntime {
     reconcile(signal?: AbortSignal, requireComplete?: boolean): Promise<void>;
     private recoverInstanceActivation;
     private recoverPendingInstanceActivation;
+    private clearRecoveryRoot;
     private readRecoveryEnvelope;
     private run;
     private readCompleteSnapshot;

package/dist/runtime/host/stateful-authority-route-runtime.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkStatefulAuthorityRouteRuntime = void 0;
+const authority_key_codec_1 = require("../locations/authority-key-codec");
 const node_crypto_1 = require("node:crypto");
 const relocation_blob_1 = require("../locations/relocation-blob");
 const routing_id_1 = require("../routing-id");
@@ -65,11 +66,19 @@ class ZLinkStatefulAuthorityRouteRuntime {
             const previous = this.appliedByMesh.get(meshName) ?? new Map();
             const status = sink.status();
             for (const pending of snapshot.pending) {
-                if (pending.targetMeshName === meshName &&
-                    (0, routing_id_1.routingIdsEqual)(status.routingId, pending.targetNodeRid) &&
+                if (pending.targetMeshName !== meshName)
+                    continue;
+                if ((0, routing_id_1.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, (0, authority_key_codec_1.encodeAuthorityKey)('instance_spot', pending.spotId), pending.pending.storeVersion, signal))
+                        await this.clearRecoveryRoot(pending.pending.requestReference, signal);
+                }
             }
             for (const [key, route] of current) {
                 if (route.meshName !== meshName)
@@ -207,19 +216,18 @@ class ZLinkStatefulAuthorityRouteRuntime {
                 }
             }, signal);
             if (aborted.kind === 'aborted' || aborted.kind === 'alreadyAborted') {
-                try {
-                    await this.options.relocationStore?.delete((0, relocation_blob_1.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;
         }
         if ((await sink.recoverPendingInstanceActivation(envelope, recovery.pending, null)) === false)
             return;
     }
+    async clearRecoveryRoot(reference, signal) {
+        if (this.options.relocationStore === undefined)
+            throw new Error('Instance activation recovery requires a Relocation Store.');
+        await this.options.relocationStore.delete((0, relocation_blob_1.relocationBlobReference)(reference), signal);
+    }
     async readRecoveryEnvelope(recovery, signal) {
         const relocationStore = this.options.relocationStore;
         if (relocationStore === undefined) {

package/dist/runtime/locations/domain-store-contract.d.ts

@@ -25,6 +25,7 @@ export interface ZLinkDomainLocationStore {
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;
+    releaseEndedReservation?(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectAbortResult>;
     prepareAggregate(request: ZLinkAggregatePrepareRequest, signal?: AbortSignal): Promise<ZLinkAggregatePrepareResult>;
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;

package/dist/runtime/locations/in-memory-authority-store.d.ts

@@ -26,6 +26,8 @@ export declare class ZLinkInMemoryAuthorityStore {
     compareExchangeAuthority(key: ZLinkAuthorityKey, expectedStoreVersion: ZLinkAuthorityStoreVersion, mutation: ZLinkAuthorityMutation, signal?: AbortSignal): Promise<ZLinkAuthorityCompareExchangeResult>;
     listAuthorities(prefix: string, cursor: ZLinkAuthorityScanCursor | undefined, limit: number, signal?: AbortSignal): Promise<ZLinkAuthorityScanResult>;
     removeAllByOwner(owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<bigint>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
+    private tryReleaseEndedReservation;
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;

package/dist/runtime/locations/in-memory-authority-store.js

@@ -171,6 +171,27 @@ class ZLinkInMemoryAuthorityStore {
             this.scanRevision++;
         return BigInt(removed);
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        signal?.throwIfAborted();
+        return this.tryReleaseEndedReservation(key, expectedStoreVersion);
+    }
+    tryReleaseEndedReservation(key, expectedStoreVersion) {
+        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, signal) {
         signal?.throwIfAborted();
         validateReserve(request);
@@ -187,15 +208,8 @@ 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((0, authority_key_codec_1.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 (!this.validation.isTargetLive(target.descriptor, target.lifecycleGeneration, target.owner)) {

package/dist/runtime/locations/in-memory-location-store.d.ts

@@ -25,6 +25,7 @@ export declare class ZLinkInMemoryLocationStore implements ZLinkDomainLocationSt
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal): Promise<ZLinkObjectCommitResult>;
     completeCreation(request: ZLinkObjectCreationCompleteRequest, signal?: AbortSignal): Promise<ZLinkObjectCreationCompleteResult>;
     readCreationTerminal(operation: ZLinkCreationOperationIdentity, signal?: AbortSignal): Promise<ZLinkCreationTerminalReadResult>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal): Promise<ZLinkObjectAbortResult>;
     prepareAggregate(request: ZLinkAggregatePrepareRequest, signal?: AbortSignal): Promise<ZLinkAggregatePrepareResult>;
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;

package/dist/runtime/locations/in-memory-location-store.js

@@ -86,6 +86,9 @@ class ZLinkInMemoryLocationStore {
     async readCreationTerminal(operation, signal) {
         return this.authority.readCreationTerminal(operation, signal);
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        return this.authority.releaseEndedReservation(key, expectedStoreVersion, signal);
+    }
     async abort(request, signal) {
         return this.authority.abort(request, signal);
     }

package/dist/runtime/locations/internal-store-contracts.d.ts

@@ -1,7 +1,7 @@
 import type { ZLinkActorLocation, ZLinkActorLocationFilter, ZLinkActorLocationKey, ZLinkLocationOwnerToken, ZLinkLocationPage, ZLinkLocationWriteIntent, ZLinkLocationWriteResult, ZLinkLocationWriteStatus, ZLinkPageRequest, ZLinkPeerLocation, ZLinkPeerLocationFilter, ZLinkPeerLocationKey, ZLinkRouteLocation, ZLinkRouteLocationFilter, ZLinkRouteLocationKey, ZLinkSpotLocation, ZLinkSpotLocationFilter, ZLinkSpotLocationKey } from './internal-location-contracts';
 import type { ZLinkDomainLocationStore } from './domain-store-contract';
 export type ZLinkAuthorityStore = Pick<ZLinkDomainLocationStore, 'readAuthority' | 'compareExchangeAuthority' | 'listAuthorities'>;
-export type ZLinkObjectCreationStore = Pick<ZLinkDomainLocationStore, 'readCreationTerminal' | 'reserve' | 'commit' | 'completeCreation' | 'abort' | 'prepareAggregate' | 'commitAggregate' | 'abortAggregate'>;
+export type ZLinkObjectCreationStore = Pick<ZLinkDomainLocationStore, 'readCreationTerminal' | 'reserve' | 'commit' | 'completeCreation' | 'abort' | 'releaseEndedReservation' | 'prepareAggregate' | 'commitAggregate' | 'abortAggregate'>;
 export type ZLinkOwnerLeaseStore = Pick<ZLinkDomainLocationStore, 'claimOwnerLease' | 'readOwnerLease' | 'renewOwnerLease' | 'releaseOwnerLease'>;
 export type ZLinkMeshNodeLocationStore = Pick<ZLinkDomainLocationStore, 'updateMeshNode' | 'removeMeshNode' | 'listMeshNodes'>;
 export type ZLinkClientServerLocationStore = Pick<ZLinkDomainLocationStore, 'updateClientServer' | 'removeClientServer' | 'listClientServers'>;

package/dist/runtime/locations/location-store-repository.d.ts

@@ -20,6 +20,7 @@ export declare class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationS
     commitAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateCommitResult>;
     private commitAggregateCore;
     abortAggregate(fence: ZLinkAggregateFence, signal?: AbortSignal): Promise<ZLinkAggregateAbortResult>;
+    releaseEndedReservation(key: ZLinkAuthorityKey, expectedStoreVersion: string, signal?: AbortSignal): Promise<boolean>;
     reserve(request: ZLinkObjectReserveRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectReserveResult>;
     commit(request: ZLinkObjectCommitRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectCommitResult>;
     abort(request: ZLinkObjectAbortRequest, signal?: AbortSignal, deadlineUnixMs?: bigint): Promise<ZLinkObjectAbortResult>;

package/dist/runtime/locations/location-store-repository.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocationStoreRepository = void 0;
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
 const Options_1 = require("../../contracts/Locations/Options");
@@ -46,7 +47,33 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
     constructor(provider, nowProvider = () => new Date()) {
         super(nowProvider);
         this.nowProvider = 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 aggregate_inventory_store_1.ZLinkAggregateInventoryStore(this.provider);
     }
     async readAuthority(key, signal) {
@@ -787,6 +814,57 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             return { kind: 'aborted' };
         }
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        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(descriptor.value.bytes).descriptor).lifecycleGeneration === snapshot.allocation.descriptorLifecycleGeneration)
+            return false;
+        const mutations = [
+            { kind: 'delete', key: rowKey }
+        ];
+        if (capacity.kind === 'found') {
+            const stored = decodeJson(capacity.value.bytes);
+            mutations.push({
+                kind: 'put',
+                key: capacityRowKey,
+                bytes: encodeJson({
+                    active: stored.active,
+                    pending: subtractCapacity(stored.pending, snapshot.allocation.capacity)
+                })
+            });
+        }
+        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';
+    }
     async reserve(request, signal, deadlineUnixMs) {
         const encodedAuthorityKey = (0, authority_key_codec_1.encodeAuthorityKey)(request.key.kind, request.key.globalId);
         const reservationId = (0, node_crypto_1.randomUUID)();
@@ -807,51 +885,8 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 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.
-                    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)) {
+                if (!(await this.releaseEndedReservation(encodedAuthorityKey, current.value.version.value, signal)))
                     return { kind: 'conflict', current: snapshot };
-                }
-                const staleCapacity = staleCapacityRead.kind === 'missing'
-                    ? emptyCapacityRecord()
-                    : decodeJson(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)
-                            })
-                        }
-                    ]
-                }, signal);
                 continue;
             }
             const [descriptorRead, leaseRead] = await Promise.all([
@@ -2942,10 +2977,9 @@ function sameCreationTarget(snapshot, target) {
         snapshot.ownerId === target.owner.ownerId &&
         snapshot.ownerLeaseGeneration === target.owner.leaseGeneration);
 }
-const CANONICAL_AUTHORITY_MAGIC = Buffer.from('ZLAU');
-function isCanonicalAuthorityPayload(payload) {
-    return (payload.byteLength >= CANONICAL_AUTHORITY_MAGIC.byteLength &&
-        Buffer.from(payload.buffer, payload.byteOffset, CANONICAL_AUTHORITY_MAGIC.byteLength).equals(CANONICAL_AUTHORITY_MAGIC));
+const relocationAuthorityCodec = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec();
+function hasRelocationAuthority(payload) {
+    return relocationAuthorityCodec.read(payload) !== undefined;
 }
 function sameLiveOwner(lease, snapshot) {
     if (lease.kind === 'missing')
@@ -3239,3 +3273,12 @@ function throwIfOperationExpired(signal, deadlineUnixMs) {
         throw new DOMException('Operation deadline exceeded.', 'TimeoutError');
     }
 }
+// Store SPI §6: preserve caller failures and classify provider failures once.
+function locationStoreProviderFailure(error, signal) {
+    if (error instanceof contracts_1.ZLinkFrameworkException ||
+        error instanceof TypeError ||
+        error instanceof RangeError ||
+        signal?.aborted === true)
+        return error;
+    return new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.Unavailable, 'Location Store provider is unavailable.', error);
+}

package/dist/runtime/spots/spot-serial-executor.js

@@ -96,7 +96,10 @@ class ZLinkSpotSerialExecutor {
         this.throwIfClosing();
         let executor = this.actorExecutors.get(actorId);
         if (executor === undefined) {
-            executor = new actors_1.ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
+            executor =
+                this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide
+                    ? this.spotSerial.createActorExecutor(actorId, this.sourceSpotId, this.actorOptions)
+                    : new actors_1.ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
             this.actorExecutors.set(actorId, executor);
         }
         return executor;

package/dist/runtime/spots/spot-serial-turn-executor.d.ts

@@ -3,6 +3,7 @@ import type { SpotId } from '../../contracts';
 import type { ZLinkFrameworkException } from '../../contracts/Errors/ZLinkFrameworkException';
 import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions, 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;
 };
@@ -19,6 +20,8 @@ export declare class ZLinkSpotSerialTurnExecutor {
     activeTurnId: number;
     constructor(yieldAllowed?: boolean, sourceSpotId?: SpotId | undefined, schedulerOptions?: ZLinkSerialSchedulerOptions);
     get isExecuting(): boolean;
+    /** Creates a passive Actor mailbox consumed by this Spot's scheduler. */
+    createActorExecutor(actorId: string, sourceSpotId: unknown, options?: ZLinkSerialSchedulerOptions): ZLinkActorSerialExecutor;
     get isCurrentTurn(): boolean;
     get hasPendingWork(): boolean;
     get lastActivityAt(): number;

package/dist/runtime/spots/spot-serial-turn-executor.js

@@ -4,6 +4,7 @@ exports.ZLinkSpotSerialTurnExecutor = void 0;
 const execution_1 = require("../execution");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const serial_execution_queue_1 = require("../execution/serial-execution-queue");
+const actor_mailbox_1 = require("../actors/actor-mailbox");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 class ZLinkSpotSerialTurnExecutor {
     yieldAllowed;
@@ -24,6 +25,10 @@ class ZLinkSpotSerialTurnExecutor {
     get isExecuting() {
         return this.depth > 0;
     }
+    /** Creates a passive Actor mailbox consumed by this Spot's scheduler. */
+    createActorExecutor(actorId, sourceSpotId, options) {
+        return new actor_mailbox_1.ZLinkActorSerialExecutor(actorId, sourceSpotId, options, this.scheduler);
+    }
     get isCurrentTurn() {
         return this.depth > 0 && (0, execution_1.isCurrentZLinkSpotSerialTurn)(this);
     }

package/dist/runtime/streams/index.d.ts

@@ -16,7 +16,6 @@ import { ZLinkStreamCodec, ZLinkStreamMessageKind, type ZLinkStreamFrameHeader,
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
 import type { ZLinkActorRouteCommitOptions, ZLinkSessionBindingConfirmationOptions, ZLinkSessionBindingIdentity } from './stream-binding-runtime-ports';
 import { ZLinkStreamSessionNodeRuntime as ZLinkStreamSessionNodeRuntimeCore, ZLinkStreamSessionRuntime as ZLinkStreamSessionRuntimeCore, type ZLinkStreamSessionNodeRuntimeOptions as ZLinkStreamSessionNodeRuntimeCoreOptions, type ZLinkStreamSessionRuntimeOptions as ZLinkStreamSessionRuntimeCoreOptions } from './stream-session-runtime';
-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';

package/dist/runtime/streams/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkStreamBindingRuntime = exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = exports.ZLinkStreamRuntimeManager = exports.DefaultZLinkSessionContext = exports.DefaultZLinkSessionActor = exports.DefaultZLinkBoundSessionFactory = exports.DefaultZLinkBoundSession = exports.ZLinkManagedStream = exports.zlinkStreamLz4CompressionCodec = exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionLifecycleCoordinator = exports.ZLinkPendingSessionRequest = void 0;
+exports.ZLinkStreamBindingRuntime = exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = exports.ZLinkStreamRuntimeManager = exports.DefaultZLinkSessionContext = exports.DefaultZLinkSessionActor = exports.DefaultZLinkBoundSessionFactory = exports.DefaultZLinkBoundSession = exports.ZLinkManagedStream = exports.zlinkStreamLz4CompressionCodec = exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionLifecycleCoordinator = void 0;
 const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
 const Options_1 = require("../../contracts/Locations/Options");
 const configuration_1 = require("../configuration");
@@ -20,8 +20,6 @@ const stream_frame_factory_1 = require("./stream-frame-factory");
 const stream_message_utils_1 = require("./stream-message-utils");
 const stream_session_runtime_1 = require("./stream-session-runtime");
 const DEFAULT_STREAM_SERVICE_SHUTDOWN_TIMEOUT_MS = 1000;
-var session_requests_1 = require("./session-requests");
-Object.defineProperty(exports, "ZLinkPendingSessionRequest", { enumerable: true, get: function () { return session_requests_1.ZLinkPendingSessionRequest; } });
 var actor_session_lifecycle_coordinator_2 = require("./actor-session-lifecycle-coordinator");
 Object.defineProperty(exports, "ZLinkActorSessionLifecycleCoordinator", { enumerable: true, get: function () { return actor_session_lifecycle_coordinator_2.ZLinkActorSessionLifecycleCoordinator; } });
 var actor_session_binding_registry_2 = require("./actor-session-binding-registry");
@@ -116,6 +114,9 @@ class ZLinkStreamRuntimeManager {
             const readablePoller = streamAdapter.createReadablePoller(socket);
             const runtime = new stream_session_runtime_1.ZLinkStreamSessionNodeRuntime({
                 nodeName,
+                heartbeatIntervalMs: streamNode.heartbeatIntervalMs,
+                heartbeatTimeoutMs: streamNode.heartbeatTimeoutMs,
+                idleTimeoutMs: streamNode.idleTimeoutMs,
                 socket,
                 createPacket: () => streamAdapter.createStreamPacket(),
                 readablePoller,