@zlink-systems/framework 0.28.0 → 0.29.1

package/dist/runtime/foundation/service-topology-registry.d.ts

@@ -58,7 +58,12 @@ export declare class ServiceTopologyRegistry {
     selectChannel(channelName: string, isReady?: (peer: AdmittedServicePeer) => boolean): AdmittedServicePeer | undefined;
     selectPlacement(isReady?: (peer: AdmittedServicePeer) => boolean): AdmittedServicePeer | undefined;
     selectObjectPlacement(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): ServiceNodeDescriptor | undefined;
+    selectObjectPlacementWithStatus(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): {
+        readonly status: ServiceObjectPlacementStatus;
+        readonly descriptor?: ServiceNodeDescriptor;
+    };
     objectPlacementStatus(stableType: string, isReady?: (descriptor: ServiceNodeDescriptor) => boolean): ServiceObjectPlacementStatus;
+    private objectPlacementCandidates;
     instanceSpotPlacementTypes(): readonly string[];
     private selectWeightedCycle;
     private rebuildSelections;

package/dist/runtime/foundation/service-topology-registry.js

@@ -181,21 +181,22 @@ class ServiceTopologyRegistry {
             .map(clonePeer), (peer) => peer.descriptor.placementWeight, (peer) => peer.descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId), isReady);
     }
     selectObjectPlacement(stableType, isReady = () => true) {
+        return this.selectObjectPlacementWithStatus(stableType, isReady).descriptor;
+    }
+    selectObjectPlacementWithStatus(stableType, isReady = () => true) {
         requireText(stableType, 'stableType');
-        return this.selectWeightedCycle(`object:${stableType}`, () => {
-            const capability = `object-type:${stableType}`;
-            return [this.local, ...this.peersByRid.values()]
-                .map((value) => ('descriptor' in value ? value.descriptor : value))
-                .filter((descriptor) => descriptor.state === 'serving' &&
-                descriptor.objectRole === 'server' &&
-                descriptor.placementWeight > 0 &&
-                descriptor.activeCapacityUsed < descriptor.activeCapacityLimit &&
-                descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit &&
-                descriptor.protocolCapabilities.includes(capability))
-                .map(cloneDescriptor);
-        }, (descriptor) => descriptor.placementWeight, (descriptor) => descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId), isReady);
+        const candidates = this.objectPlacementCandidates(stableType, isReady);
+        if (candidates.status !== 'available')
+            return { status: candidates.status };
+        const descriptor = this.selectWeightedCycle(`object:${stableType}`, () => this.objectPlacementCandidates(stableType).eligible.map(cloneDescriptor), (descriptor) => descriptor.placementWeight, (descriptor) => descriptor.nodeRoutingId, (left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId), isReady);
+        return descriptor === undefined
+            ? { status: 'unavailable' }
+            : { status: 'available', descriptor };
     }
     objectPlacementStatus(stableType, isReady = () => true) {
+        return this.objectPlacementCandidates(stableType, isReady).status;
+    }
+    objectPlacementCandidates(stableType, isReady = () => true) {
         requireText(stableType, 'stableType');
         const capability = `object-type:${stableType}`;
         const supported = [
@@ -205,15 +206,13 @@ class ServiceTopologyRegistry {
             descriptor.objectRole === 'server' &&
             descriptor.protocolCapabilities.includes(capability));
         if (supported.length === 0)
-            return 'unsupported';
+            return { status: 'unsupported', eligible: [] };
         const withCapacity = supported.filter((descriptor) => descriptor.activeCapacityUsed < descriptor.activeCapacityLimit &&
             descriptor.pendingCapacityUsed < descriptor.pendingCapacityLimit);
         if (withCapacity.length === 0)
-            return 'capacity';
+            return { status: 'capacity', eligible: [] };
         const weighted = withCapacity.filter((descriptor) => descriptor.placementWeight > 0);
-        if (weighted.length === 0)
-            return 'unsupported';
-        return weighted.some(isReady) ? 'available' : 'unavailable';
+        return { status: weighted.some(isReady) ? 'available' : 'unavailable', eligible: weighted };
     }
     instanceSpotPlacementTypes() {
         const prefix = 'instance-spot-type:';

package/dist/runtime/handlers/handler-instance-scope.js

@@ -158,7 +158,7 @@ class LifecycleHandlerInstanceScope {
         }
     }
     async dispose(detachedTaskRunner) {
-        const disposeFromActiveInvocation = activeLifecycleScope.getStore() === this;
+        const disposeFromActiveInvocation = this.activeInvocations > 0 && activeLifecycleScope.getStore() === this;
         const disposal = this.beginDisposeCore();
         if (disposal.deferred !== undefined) {
             startOutsideLifecycleInvocation(() => {

package/dist/runtime/host/actor-placement-coordinator.d.ts

@@ -1,5 +1,5 @@
 import type { ActorRef, RoutingId, ZLinkActorCreateResult } from '../../contracts';
-import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken, ZLinkObjectReserveRequest } from '../locations/internal-location-contracts';
 import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
 import type { ServiceActorCreateRecord } from '../foundation/service-stateful-wire-codec';
 import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
@@ -14,6 +14,7 @@ export interface ZLinkActorPlacementTarget {
     readonly sourceNodeGeneration: bigint;
 }
 export interface ZLinkActorPlacementCoordinatorOptions {
+    readonly actorRelocationPolicy?: (meshName: string, stableType: string) => ZLinkObjectReserveRequest['actorRelocationPolicy'];
     readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
     readonly target: (meshName: string | undefined, stableType: string, signal?: AbortSignal, excludedNodeRids?: ReadonlySet<string>) => Promise<ZLinkActorPlacementTarget | undefined>;
     readonly remoteCreate: (meshName: string, targetNodeRid: string, request: Omit<ServiceActorCreateRecord, 'kind' | 'correlation'>, timeoutMs: number) => Promise<ServiceUserSpotOperationResult>;

package/dist/runtime/host/actor-placement-coordinator.js

@@ -61,7 +61,8 @@ class ZLinkActorPlacementCoordinator {
                     },
                     target: reservationTarget(target),
                     creatingPayload,
-                    capacity: { actors: 1, spots: 0 }
+                    capacity: { actors: 1, spots: 0 },
+                    actorRelocationPolicy: this.options.actorRelocationPolicy?.(target.meshName, stableType)
                 }, deadline.signal, BigInt(deadlineUnixMs));
                 const existing = existingActor(reserved, actorId, stableType);
                 if (existing !== undefined) {

package/dist/runtime/host/actor-runtime-options-factory.d.ts

@@ -15,6 +15,7 @@ import type { ZLinkRuntimeAdmissionGate } from '../admission';
 import type { ZLinkRemoteActorPacketTarget } from '../actors';
 import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
 export interface ZLinkActorRuntimeOptionsFactoryOptions {
+    readonly terminateActorActivation: (actor: ZLinkActor, terminal: () => Promise<void>) => Promise<void>;
     readonly registration: ZLinkFrameworkRegistration;
     /** Message flow tracer, so a failed deferred Join records its cause on the flow. */
     readonly messageFlow?: () => import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
@@ -61,7 +62,7 @@ export interface ZLinkActorRuntimeOptionsFactoryOptions {
 export declare class ZLinkActorRuntimeOptionsFactory {
     private readonly options;
     constructor(options: ZLinkActorRuntimeOptionsFactoryOptions);
-    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'publishActorAuthority' | 'locationLifecycle' | 'boundSessionFactory' | 'actorTransferRegistry' | 'shutdownSignal' | 'metrics' | 'admission'>;
+    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'terminateActorActivation' | 'publishActorAuthority' | 'locationLifecycle' | 'boundSessionFactory' | 'actorTransferRegistry' | 'shutdownSignal' | 'metrics' | 'admission'>;
     createActorClientOptions(): ConstructorParameters<typeof DefaultZLinkActorClient>[0];
     private actorBelongsToMesh;
 }

package/dist/runtime/host/actor-runtime-options-factory.js

@@ -13,6 +13,7 @@ class ZLinkActorRuntimeOptionsFactory {
     createActorManagerOptions() {
         const actorTransferRegistry = this.options.actorTransferRegistry;
         return {
+            terminateActorActivation: this.options.terminateActorActivation,
             actorMeshNameProvider: this.options.actorMeshName,
             actorLeaveSpot: (meshName, spotId, actor, signal) => {
                 const spotManager = this.options.spotManager();

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

@@ -155,7 +155,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private registerInstanceApplicationLifecycle;
     setActorManager(actorManager: DefaultZLinkActorManager): void;
     setSpotManager(spotManager: DefaultZLinkSpotManager): void;
-    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'locationLifecycle' | 'boundSessionFactory' | 'shutdownSignal' | 'admission' | 'activationAdmission' | 'placementCreate'>;
+    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'terminateActorActivation' | 'locationLifecycle' | 'boundSessionFactory' | 'shutdownSignal' | 'admission' | 'activationAdmission' | 'placementCreate'>;
     createActorClientOptions(): ConstructorParameters<typeof DefaultZLinkActorClient>[0];
     createLocationHandleResolver(): ZLinkStoreLocationResolvers | undefined;
     createSpotManagerOptions(): Partial<ZLinkSpotManagerOptions>;

package/dist/runtime/host/index.js

@@ -1511,6 +1511,8 @@ class ZLinkFrameworkRuntimeHost {
         }
         this.actorPlacement ??= new actor_placement_coordinator_1.ZLinkActorPlacementCoordinator({
             store: locationStore,
+            actorRelocationPolicy: (meshName, stableType) => this.options.registration.spotNodes.get(meshName)?.actorFactoryRegistrations?.[stableType]
+                ?.relocation.kind,
             remoteCreate: (meshName, targetNodeRid, request, timeoutMs) => {
                 const node = this.spotNodeRuntime?.meshNode(meshName);
                 if (node === undefined) {
@@ -1546,13 +1548,11 @@ class ZLinkFrameworkRuntimeHost {
                 const descriptors = await (0, location_store_pages_1.listAllMeshNodeDescriptors)(locationStore, meshName, signal);
                 const selected = await selectReadyLocationPlacementDescriptor(descriptors, meshNode, signal, (descriptor) => {
                     const capability = descriptor.objectCapabilities.find((candidate) => candidate.objectKind === 'actor' && candidate.stableType === stableType);
-                    const actors = descriptor.populationCapacity.actors;
                     return (descriptor.state === contracts_1.ZLinkFrameworkRuntimeState.Serving &&
                         descriptor.objectRole === 'server' &&
                         descriptor.placementWeight > 0 &&
                         descriptor.entrySpotId !== undefined &&
                         excludedNodeRids?.has(String(descriptor.rid)) !== true &&
-                        (actors.limit === 0 || actors.active + actors.reserved < actors.limit) &&
                         capability !== undefined);
                 });
                 if (selected === undefined)
@@ -1832,6 +1832,7 @@ class ZLinkFrameworkRuntimeHost {
     }
     actorRuntimeOptionsFactory() {
         return new actor_runtime_options_factory_1.ZLinkActorRuntimeOptionsFactory({
+            terminateActorActivation: (actor, terminal) => this.spotNodeRuntime?.terminateActorActivation(actor, terminal) ?? terminal(),
             registration: this.options.registration,
             messageFlow: () => this.createDispatchErrorReporter(this.runtimeOrPreStartErrorSink).flow,
             routeTransport: this.routeTransport,

package/dist/runtime/host/instance-activation-authority.d.ts

@@ -27,6 +27,5 @@ export declare class ZLinkInstanceActivationAuthority implements ServiceAsyncIns
     abort(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation): Promise<void>;
     private requireOwner;
     private deleteOrphan;
-    private awaitConcurrentActivation;
     private requirePending;
 }

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

@@ -1,5 +1,6 @@
 import type { ZLinkLocationOwnerToken, ZLinkLocationPage, ZLinkLocationWriteIntent, ZLinkLocationWriteResult, ZLinkLocationWriteStatus, ZLinkMeshNodeDescriptor, ZLinkMeshNodeDescriptorKey, ZLinkClientServerServerDescriptor, ZLinkClientServerServerDescriptorKey, ZLinkFanoutPublisherDescriptor, ZLinkFanoutPublisherDescriptorKey, ZLinkOwnerLeaseClaimResult, ZLinkOwnerLeaseReadResult, ZLinkOwnerLeaseReleaseResult, ZLinkOwnerLeaseRenewResult, ZLinkPageRequest } from '../../contracts/Locations/Models';
-import type { ZLinkAggregateAbortResult, ZLinkAggregateCommitResult, ZLinkAggregateFence, ZLinkAggregatePrepareRequest, ZLinkAggregatePrepareResult, ZLinkAuthorityCompareExchangeResult, ZLinkAuthorityKey, ZLinkAuthorityMutation, ZLinkAuthorityReadResult, ZLinkAuthorityScanCursor, ZLinkAuthorityScanResult, ZLinkAuthorityStoreVersion, ZLinkCreationOperationIdentity, ZLinkCreationTerminalReadResult, ZLinkObjectAbortRequest, ZLinkObjectAbortResult, ZLinkObjectCommitRequest, ZLinkObjectCommitResult, ZLinkObjectCreationCompleteRequest, ZLinkObjectCreationCompleteResult, ZLinkObjectReserveRequest, ZLinkObjectReserveResult } from '../../contracts/Locations/Authority';
+import type { ZLinkAggregateAbortResult, ZLinkAggregateCommitResult, ZLinkAggregateFence, ZLinkAggregatePrepareRequest, ZLinkAggregatePrepareResult, ZLinkAuthorityCompareExchangeResult, ZLinkAuthorityKey, ZLinkAuthorityMutation, ZLinkAuthorityReadResult, ZLinkAuthorityScanCursor, ZLinkAuthorityScanResult, ZLinkAuthorityStoreVersion, ZLinkCreationOperationIdentity, ZLinkCreationTerminalReadResult, ZLinkObjectAbortRequest, ZLinkObjectAbortResult, ZLinkObjectCommitRequest, ZLinkObjectCommitResult, ZLinkObjectCreationCompleteRequest, ZLinkObjectCreationCompleteResult, ZLinkObjectReserveResult } from '../../contracts/Locations/Authority';
+import type { ZLinkObjectReserveRequest } from './internal-location-contracts';
 /**
  * Framework-private domain repository. Provider implementations never
  * implement this interface; the framework maps it to the opaque Store SPI.
@@ -25,6 +26,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

@@ -1,5 +1,6 @@
 import type { ZLinkAggregateAbortResult, ZLinkAggregateCommitResult, ZLinkAggregateFence, ZLinkAggregatePrepareRequest, ZLinkAggregatePrepareResult, ZLinkAuthorityCompareExchangeResult, ZLinkAuthorityKey, ZLinkAuthorityMutation, ZLinkAuthorityReadResult, ZLinkAuthorityScanCursor, ZLinkAuthorityScanResult, ZLinkAuthorityStoreVersion, ZLinkCapacityVector, ZLinkLocationOwnerToken, ZLinkMeshNodeDescriptorKey, ZLinkObjectAbortRequest, ZLinkObjectAbortResult, ZLinkObjectCommitRequest, ZLinkObjectCommitResult, ZLinkObjectCreationCompleteRequest, ZLinkObjectCreationCompleteResult, ZLinkObjectReserveRequest, ZLinkObjectReserveResult, ZLinkCreationOperationIdentity, ZLinkCreationTerminalReadResult } from './internal-location-contracts';
 export interface ZLinkInMemoryAuthorityValidation {
+    isOwnerLive(owner: ZLinkLocationOwnerToken): boolean;
     isTargetLive(descriptor: ZLinkMeshNodeDescriptorKey, lifecycleGeneration: bigint, owner: ZLinkLocationOwnerToken): boolean;
     placementCapacityAvailable?(descriptor: ZLinkMeshNodeDescriptorKey, requested: ZLinkCapacityVector, currentReserved: ZLinkCapacityVector, currentActive: ZLinkCapacityVector): boolean;
     identityClaimed?(authorityKey: string): boolean;
@@ -26,6 +27,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

@@ -6,12 +6,15 @@ const stream_wire_1 = require("@zlink-systems/stream-wire");
 const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const Stores_1 = require("../../contracts/Locations/Stores");
 const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("../../contracts");
 const actor_join_recovery_codec_1 = require("../foundation/actor-join-recovery-codec");
 const authority_key_codec_1 = require("./authority-key-codec");
 const opaque_record_key_1 = require("./opaque-record-key");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
 const MAX_GENERATION = 0x7fffffffffffffffn;
 const CREATION_TERMINAL_RETENTION_MS = 5 * 60 * 1000;
 const MAX_U64 = stream_wire_1.UINT64_MAX;
+const relocationAuthorityCodec = new service_relocation_runtime_1.ServiceRelocationAuthorityPayloadCodec();
 /**
  * In-memory reference provider for the provider-owned authority state machine.
  * Opaque payload bytes are copied but never parsed.
@@ -171,6 +174,46 @@ class ZLinkInMemoryAuthorityStore {
             this.scanRevision++;
         return BigInt(removed);
     }
+    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+        signal?.throwIfAborted();
+        return this.tryReleaseEndedReservation(key, expectedStoreVersion);
+    }
+    tryReleaseEndedReservation(key, expectedStoreVersion, request) {
+        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 contracts_1.ZLinkFrameworkException(contracts_1.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, signal) {
         signal?.throwIfAborted();
         validateReserve(request);
@@ -184,18 +227,10 @@ class ZLinkInMemoryAuthorityStore {
                 current.snapshot.allocation.stableType !== request.intent.stableType) {
                 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((0, authority_key_codec_1.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 (!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>;
@@ -71,7 +72,7 @@ export declare class ZLinkInMemoryLocationStore implements ZLinkDomainLocationSt
     private transitionActorTransfer;
     private remove;
     private removeByOwner;
-    private isOwnerLive;
+    private liveOwnerLease;
     private bump;
     private removeFanoutByOwner;
     private bumpScope;