@zlink-systems/framework 0.29.0 → 0.30.0

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

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocationStoreRepository = void 0;
 const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const service_authority_payload_codec_1 = require("../foundation/service-authority-payload-codec");
+const actor_authority_payload_codec_1 = require("../actors/actor-authority-payload-codec");
+const contracts_1 = require("../../contracts");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
 const Options_1 = require("../../contracts/Locations/Options");
-const contracts_1 = require("../../contracts");
+const contracts_2 = require("../../contracts");
 const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
 const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
@@ -215,9 +218,27 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                         payload: Buffer.from(mutation.payload)
                     }
                 };
+            const actor = mutation.kind !== 'delete' && record.snapshot.allocation.objectKind === 'actor'
+                ? (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(mutation.payload))
+                : undefined;
+            const previousActor = actor === undefined
+                ? undefined
+                : (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(record.snapshot.payload));
+            const membershipConditions = actor?.currentSpotKind === contracts_1.ZLinkSpotKind.User &&
+                (previousActor?.currentSpotKind !== contracts_1.ZLinkSpotKind.User ||
+                    previousActor.currentSpotId !== actor.currentSpotId ||
+                    previousActor.currentSpotGeneration !== actor.currentSpotGeneration)
+                ? await this.userSpotMembershipConditions(actor.currentSpotId, actor.currentSpotGeneration, signal, {
+                    ownerId: record.snapshot.ownerId,
+                    leaseGeneration: record.snapshot.ownerLeaseGeneration
+                })
+                : [];
+            if (membershipConditions === undefined)
+                return { kind: 'conflict', current: snapshot };
             const result = await this.provider.write({
                 conditions: [
                     { kind: 'version', key: rowKey, expected: current.value.version },
+                    ...membershipConditions,
                     ...(mutation.kind === 'restore'
                         ? []
                         : [
@@ -654,7 +675,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                     sha256Hex(membership) !== entry.membershipMutationSha256) {
                     throw new Error('Aggregate participant staging checksum does not match inventory.');
                 }
-                authorityRows.push({ key: rowKeyForParticipant, current, record, entry });
+                authorityRows.push({ key: rowKeyForParticipant, current, record, entry, payload });
             }
             const targetDescriptorKey = meshKey(aggregate.targetDescriptor.meshName, aggregate.targetDescriptor.rid);
             const targetLeaseKey = ownerKey(aggregate.targetOwner.ownerId);
@@ -717,11 +738,34 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                     bytes: encodeJson(capacity)
                 });
             }
+            const membershipConditions = [];
+            for (const row of authorityRows) {
+                if (row.record.snapshot.allocation.objectKind !== 'actor')
+                    continue;
+                const actor = (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(row.payload));
+                if (actor?.currentSpotKind !== contracts_1.ZLinkSpotKind.User)
+                    continue;
+                const spotKey = (0, authority_key_codec_1.encodeAuthorityKey)('user_spot', actor.currentSpotId);
+                const participantSpot = authorityRows.find((candidate) => candidate.entry.authorityKey === spotKey.value);
+                if (participantSpot !== undefined) {
+                    if (participantSpot.record.snapshot.allocation.objectKind !== 'user_spot' ||
+                        participantSpot.record.snapshot.objectGeneration !== actor.currentSpotGeneration)
+                        return { kind: 'stale' };
+                    continue;
+                }
+                if (membershipConditions.some((condition) => condition.key.value === authorityKey(spotKey.value).value))
+                    continue;
+                const conditions = await this.userSpotMembershipConditions(actor.currentSpotId, actor.currentSpotGeneration, signal, aggregate.targetOwner);
+                if (conditions === undefined)
+                    return { kind: 'stale' };
+                membershipConditions.push(...conditions.filter((condition) => !membershipConditions.some((existing) => existing.key.value === condition.key.value)));
+            }
             const published = await this.provider.write({
                 conditions: [
                     { kind: 'version', key: rowKey, expected: aggregateRead.value.version },
                     versionCondition(targetDescriptorKey, descriptorRead),
                     leaseValueCondition(targetLeaseKey, aggregate.targetOwner),
+                    ...membershipConditions,
                     ...[...capacityReads.entries()].map(([value, read]) => ({
                         kind: 'version',
                         key: capacityKeys.get(value),
@@ -814,18 +858,21 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             return { kind: 'aborted' };
         }
     }
-    async releaseEndedReservation(key, expectedStoreVersion, signal) {
+    async releaseEndedReservation(key, expectedStoreVersion, signal, request) {
+        return ((await this.tryReleaseEndedReservation(key, expectedStoreVersion, signal, request)) ===
+            'reclaimed');
+    }
+    async tryReleaseEndedReservation(key, expectedStoreVersion, signal, request) {
         const rowKey = authorityKey(key.value);
         const current = await this.provider.read(rowKey, signal);
         if (current.kind === 'missing' || current.value.version.value !== expectedStoreVersion)
-            return false;
+            return 'conflict';
         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;
+        if (snapshot.allocation.state === 'active'
+            ? request === undefined
+            : snapshot.pendingCreation === undefined)
+            return 'notReclaimable';
         const leaseKey = ownerKey(snapshot.ownerId);
         const descriptorKey = meshKey(snapshot.allocation.descriptor.meshName, snapshot.allocation.descriptor.rid);
         const capacityRowKey = capacityKey(snapshot.allocation.descriptor.meshName, String(snapshot.allocation.descriptor.rid));
@@ -836,23 +883,95 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
         ]);
         if (lease.kind === 'found' && lease.value.expiresAt === undefined)
             throw new Error('Location Store owner lease record is invalid.');
-        if (sameLiveOwner(lease, snapshot) &&
+        const ownerLive = sameLiveOwner(lease, snapshot);
+        if (snapshot.allocation.state === 'active') {
+            if (ownerLive)
+                return 'notReclaimable';
+            let unavailable = record.aggregate !== undefined || hasRelocationAuthority(snapshot.payload);
+            if (snapshot.allocation.objectKind !== 'actor') {
+                const spot = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload);
+                unavailable ||=
+                    spot === undefined ||
+                        spot.kind !== request?.key.kind ||
+                        spot.stableType !== request.intent.stableType ||
+                        spot.spotId !== request.key.globalId ||
+                        spot.activationRecovery !== undefined;
+                if (spot?.kind === 'user_spot') {
+                    // The snapshot starts only after the old owner's lease was found invalid.
+                    for (const prefix of [`${PREFIX}actor:`, `${AUTHORITY_PREIMAGE_PREFIX}actor\0`]) {
+                        membershipSnapshot: for (;;) {
+                            let snapshotHasMember = false;
+                            let cursor;
+                            do {
+                                const page = await this.provider.scan({ prefix, cursor, limit: Stores_1.ZLINK_PROVIDER_MAX_PAGE_SIZE }, signal);
+                                if (page.kind === 'expired')
+                                    continue membershipSnapshot;
+                                for (const item of page.value.items) {
+                                    if (prefix === `${PREFIX}actor:`) {
+                                        const actor = normalizeActor(decodeJson(item.value.bytes).descriptor);
+                                        snapshotHasMember ||=
+                                            actor.spotKind === contracts_1.ZLinkSpotKind.User &&
+                                                String(actor.spotId) === spot.spotId &&
+                                                actor.spotGeneration === snapshot.objectGeneration;
+                                    }
+                                    else {
+                                        const authority = decodeAuthorityRecord(item.value.bytes).snapshot;
+                                        if (authority.allocation.objectKind !== 'actor')
+                                            continue;
+                                        const actor = (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(authority.payload));
+                                        snapshotHasMember ||=
+                                            actor?.currentSpotKind === contracts_1.ZLinkSpotKind.User &&
+                                                actor.currentSpotId === spot.spotId &&
+                                                actor.currentSpotGeneration === snapshot.objectGeneration;
+                                    }
+                                }
+                                cursor = page.value.nextCursor;
+                            } while (cursor !== undefined);
+                            unavailable ||= snapshotHasMember;
+                            break;
+                        }
+                    }
+                }
+            }
+            if (unavailable || request?.actorRelocationPolicy !== 'disabled')
+                throw new contracts_2.ZLinkFrameworkException(contracts_2.ZLinkFrameworkErrorKind.Unavailable, 'Object owner lease is unavailable.');
+        }
+        else if (ownerLive &&
             descriptor.kind === 'found' &&
             reviveMeshDescriptor(decodeCanonicalDescriptorRecord(descriptor.value.bytes).descriptor).lifecycleGeneration === snapshot.allocation.descriptorLifecycleGeneration)
-            return false;
+            return 'notReclaimable';
+        if (snapshot.allocation.state !== 'active' &&
+            (record.aggregate !== undefined || hasRelocationAuthority(snapshot.payload)))
+            return 'notReclaimable';
         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)
-                })
-            });
+            try {
+                mutations.push({
+                    kind: 'put',
+                    key: capacityRowKey,
+                    bytes: encodeJson({
+                        active: snapshot.allocation.state === 'active'
+                            ? subtractCapacity(stored.active, snapshot.allocation.capacity)
+                            : stored.active,
+                        pending: snapshot.allocation.state === 'reserved'
+                            ? subtractCapacity(stored.pending, snapshot.allocation.capacity)
+                            : stored.pending
+                    })
+                });
+            }
+            catch (error) {
+                if (!(error instanceof contracts_2.ZLinkFrameworkException) ||
+                    error.kind !== contracts_2.ZLinkFrameworkErrorKind.DataLost)
+                    throw error;
+                const observed = await this.provider.read(rowKey, signal);
+                if (observed.kind === 'missing' ||
+                    observed.value.version.value !== current.value.version.value)
+                    return 'conflict';
+                throw error;
+            }
         }
         const result = await this.provider.write({
             conditions: [
@@ -863,11 +982,12 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             ],
             mutations
         }, signal);
-        return result.kind === 'applied';
+        return result.kind === 'applied' ? 'reclaimed' : 'conflict';
     }
     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)();
+        let reclaimVersion;
         for (;;) {
             throwIfOperationExpired(signal, deadlineUnixMs);
             const rowKey = authorityKey(encodedAuthorityKey.value);
@@ -882,19 +1002,24 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                     snapshot.allocation.stableType !== request.intent.stableType) {
                     return { kind: 'typeMismatch', current: snapshot };
                 }
-                if (snapshot.allocation.state === 'active') {
-                    return { kind: 'alreadyExists', current: snapshot };
-                }
-                if (!(await this.releaseEndedReservation(encodedAuthorityKey, current.value.version.value, signal)))
+                if (reclaimVersion !== undefined && snapshot.storeVersion.value !== reclaimVersion)
                     return { kind: 'conflict', current: snapshot };
+                const reclaim = await this.tryReleaseEndedReservation(encodedAuthorityKey, current.value.version.value, signal, request);
+                if (reclaim === 'notReclaimable')
+                    return snapshot.allocation.state === 'active'
+                        ? { kind: 'alreadyExists', current: snapshot }
+                        : { kind: 'conflict', current: snapshot };
+                reclaimVersion = reclaim === 'conflict' ? snapshot.storeVersion.value : undefined;
                 continue;
             }
+            if (reclaimVersion !== undefined)
+                return { kind: 'conflict', current: { kind: 'missing', storeNow: current.storeNow } };
             const [descriptorRead, leaseRead] = await Promise.all([
                 this.provider.read(descriptorKey, signal),
                 this.provider.read(leaseKey, signal)
             ]);
             const descriptor = liveTargetDescriptor(descriptorRead, leaseRead, request.target);
-            if (descriptor === undefined || descriptor.state !== contracts_1.ZLinkFrameworkRuntimeState.Serving) {
+            if (descriptor === undefined || descriptor.state !== contracts_2.ZLinkFrameworkRuntimeState.Serving) {
                 return { kind: 'conflict', current: { kind: 'missing', storeNow: current.storeNow } };
             }
             const [capacityRead, objectGenerationRead, authorityOwnerGenerationRead] = await Promise.all([
@@ -1171,6 +1296,14 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             if (retentionMs <= 0) {
                 throw new RangeError('Creation terminal expiry must be the live operation deadline plus five minutes.');
             }
+            const actor = request.completion.kind === 'created'
+                ? (0, actor_authority_payload_codec_1.decodeActorAuthorityPayload)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(request.completion.readyPayload))
+                : undefined;
+            const membershipConditions = actor?.currentSpotKind === contracts_1.ZLinkSpotKind.User
+                ? await this.userSpotMembershipConditions(actor.currentSpotId, actor.currentSpotGeneration, signal, request.target.owner)
+                : [];
+            if (membershipConditions === undefined)
+                return { kind: 'stale' };
             const mutations = request.completion.kind === 'created'
                 ? [
                     {
@@ -1210,6 +1343,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 conditions: [
                     { kind: 'version', key: rowKey, expected: current.value.version },
                     { kind: 'missing', key: terminalRowKey },
+                    ...membershipConditions,
                     versionCondition(descriptorKey, descriptorRead),
                     leaseValueCondition(leaseKey, request.target.owner),
                     conditionFor(capacityRowKey, capacityRead)
@@ -1472,7 +1606,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
         return this.listOwnedLocations(`${PREFIX}spot:`, page, normalizeSpot, (value) => matchesSpot(value, filter), signal);
     }
     async updateActor(location, intent, signal) {
-        return this.updateOwnedLocation(actorKey(location.meshName, location.actorId), normalizeActor(location), intent, signal);
+        return this.updateOwnedLocation(actorKey(location.meshName, location.actorId), normalizeActor(location), intent, signal, location);
     }
     async removeActor(key, owner, signal) {
         return this.removeOwnedLocation(actorKey(key.meshName, key.actorId), owner, signal);
@@ -1841,7 +1975,37 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             continuationToken: result.value.nextCursor?.value
         };
     }
-    async updateOwnedLocation(rowKey, location, intent, signal) {
+    async userSpotMembershipConditions(spotId, objectGeneration, signal, conditionedOwner) {
+        const key = authorityKey((0, authority_key_codec_1.encodeAuthorityKey)('user_spot', spotId).value);
+        const read = await this.provider.read(key, signal);
+        if (read.kind === 'missing')
+            return undefined;
+        const record = decodeAuthorityRecord(read.value.bytes);
+        const snapshot = record.snapshot;
+        if (record.aggregate !== undefined ||
+            snapshot.allocation.objectKind !== 'user_spot' ||
+            snapshot.allocation.state !== 'active' ||
+            snapshot.objectGeneration !== objectGeneration ||
+            (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload)?.kind !== 'user_spot')
+            return undefined;
+        const leaseKey = ownerKey(snapshot.ownerId);
+        const lease = await this.provider.read(leaseKey, signal);
+        if (!sameLiveOwner(lease, snapshot))
+            return undefined;
+        return [
+            { kind: 'version', key, expected: read.value.version },
+            ...(conditionedOwner?.ownerId === snapshot.ownerId &&
+                conditionedOwner.leaseGeneration === snapshot.ownerLeaseGeneration
+                ? []
+                : [
+                    leaseValueCondition(leaseKey, {
+                        ownerId: snapshot.ownerId,
+                        leaseGeneration: snapshot.ownerLeaseGeneration
+                    })
+                ])
+        ];
+    }
+    async updateOwnedLocation(rowKey, location, intent, signal, membership) {
         const leaseKey = ownerKey(location.ownerId);
         const [lease, current] = await Promise.all([
             this.provider.read(leaseKey, signal),
@@ -1886,13 +2050,25 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
         else if (intent === 2) {
             return rejected(lease.value.storeNow);
         }
+        const previousMembership = current.kind === 'found' && membership !== undefined
+            ? decodeJson(current.value.bytes).descriptor
+            : undefined;
+        const membershipConditions = membership?.spotKind === contracts_1.ZLinkSpotKind.User &&
+            (previousMembership?.spotKind !== contracts_1.ZLinkSpotKind.User ||
+                String(previousMembership.spotId) !== String(membership.spotId) ||
+                BigInt(previousMembership.spotGeneration) !== membership.spotGeneration)
+            ? await this.userSpotMembershipConditions(String(membership.spotId), membership.spotGeneration, signal, { ownerId: location.ownerId, leaseGeneration: locationOwnerGeneration(location) })
+            : [];
+        if (membershipConditions === undefined)
+            return rejected(lease.value.storeNow);
         const result = await this.provider.write({
             conditions: [
                 leaseValueCondition(leaseKey, {
                     ownerId: location.ownerId,
                     leaseGeneration: locationOwnerGeneration(location)
                 }),
-                rowCondition
+                rowCondition,
+                ...membershipConditions
             ],
             mutations: [
                 {
@@ -2880,7 +3056,7 @@ function liveTargetDescriptor(descriptorRead, leaseRead, target) {
         descriptor.lifecycleGeneration === target.nodeLifecycleGeneration &&
         descriptor.ownerId === target.owner.ownerId &&
         descriptor.leaseGeneration === target.owner.leaseGeneration &&
-        descriptor.objectRole === contracts_1.ZLinkObjectRole.Server &&
+        descriptor.objectRole === contracts_2.ZLinkObjectRole.Server &&
         lease.ownerId === target.owner.ownerId &&
         BigInt(lease.leaseGeneration) === target.owner.leaseGeneration &&
         leaseRead.value.expiresAt !== undefined &&
@@ -2941,7 +3117,7 @@ function adjustCapacity(usage, delta, direction) {
         const key = capacityTypeKey(delta.spotType);
         const next = (spotTypes[key] ?? 0) + direction * delta.spotType.count;
         if (next < 0)
-            throw new Error('Provider capacity counter underflow.');
+            throw new contracts_2.ZLinkFrameworkException(contracts_2.ZLinkFrameworkErrorKind.DataLost, 'Provider capacity counter underflow.');
         if (next === 0)
             delete spotTypes[key];
         else
@@ -2950,7 +3126,7 @@ function adjustCapacity(usage, delta, direction) {
     const actors = usage.actors + direction * delta.actors;
     const spots = usage.spots + direction * delta.spots;
     if (actors < 0 || spots < 0)
-        throw new Error('Provider capacity counter underflow.');
+        throw new contracts_2.ZLinkFrameworkException(contracts_2.ZLinkFrameworkErrorKind.DataLost, 'Provider capacity counter underflow.');
     return { actors, spots, spotTypes };
 }
 function capacityTypeKey(value) {
@@ -3275,10 +3451,10 @@ function throwIfOperationExpired(signal, deadlineUnixMs) {
 }
 // Store SPI §6: preserve caller failures and classify provider failures once.
 function locationStoreProviderFailure(error, signal) {
-    if (error instanceof contracts_1.ZLinkFrameworkException ||
+    if (error instanceof contracts_2.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);
+    return new contracts_2.ZLinkFrameworkException(contracts_2.ZLinkFrameworkErrorKind.Unavailable, 'Location Store provider is unavailable.', error);
 }

package/dist/runtime/locations/resolvers.d.ts

@@ -1,6 +1,6 @@
 import type { ActorRef, RoutingId, SpotId } from '../../contracts/Common';
 import { type SpotHandle, type ZLinkActorSpotHandleResolver, type ZLinkSpotHandleResolver, type ResolvedSpotHandle } from '../spots/spot-handle';
-import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget, ZLinkInstanceReactivationRoute } from '../spots/spot-routing-internal';
 import { ZLinkFrameworkRuntimeState, ZLinkLocationRole, type ZLinkActorLocation, type ZLinkActorLocationKey, type ZLinkLocationReadiness, type ZLinkLocationRuntimeQuery, type ZLinkPeerLocation, type ZLinkPeerLocationFilter, type ZLinkPeerLocationResolver, type ZLinkRouteLocation, type ZLinkRouteLocationKey, type ZLinkSpotLocation, type ZLinkSpotLocationKey } from './internal-location-contracts';
 import type { ZLinkActorLocationStore, ZLinkAuthorityStore, ZLinkMeshNodeLocationStore, ZLinkPeerLocationStore, ZLinkRouteLocationStore, ZLinkSpotLocationStore } from './internal-store-contracts';
 import { ZLinkOwnerLeaseTracker } from './lease-tracker';
@@ -135,6 +135,7 @@ export declare class ZLinkAuthoritySpotRouteResolver implements ZLinkSpotRouteRe
     private readonly routeEpochs;
     private readonly activeResolutions;
     constructor(store: ZLinkAuthorityStore, routerChannelIdForMesh: (meshName: string) => string, fallback?: ZLinkSpotRouteResolver | undefined, leaseTracker?: ZLinkOwnerLeaseTracker | undefined, routeCacheMaxAgeMs?: number, monotonicNowMs?: () => number, targetNodeStateResolver?: ((meshName: string, nodeRid: RoutingId, expectedLifecycleGeneration: bigint, signal?: AbortSignal) => Promise<ZLinkFrameworkRuntimeState | undefined>) | undefined);
+    resolve(spotId: RoutingId, signal: AbortSignal | undefined, instanceIntent: true): Promise<ZLinkSpotRouteTarget | ZLinkInstanceReactivationRoute>;
     resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget>;
     invalidate(spotId: RoutingId): void;
     private invalidateCore;

package/dist/runtime/locations/resolvers.js

@@ -583,7 +583,7 @@ class ZLinkAuthoritySpotRouteResolver {
         this.monotonicNowMs = monotonicNowMs;
         this.targetNodeStateResolver = targetNodeStateResolver;
     }
-    async resolve(spotId, signal) {
+    async resolve(spotId, signal, instanceIntent) {
         const key = String(spotId);
         const prepared = await this.lane.run(() => this.beginResolutionCore(key));
         try {
@@ -606,6 +606,15 @@ class ZLinkAuthoritySpotRouteResolver {
                             leaseGeneration: current.ownerLeaseGeneration
                         }, signal);
                     if (remainingLeaseMs !== undefined && remainingLeaseMs <= 0) {
+                        if (instanceIntent === true && ready?.kind === 'instance_spot') {
+                            return {
+                                kind: 'coldActivation',
+                                spotId,
+                                spotKind: Spots_1.ZLinkSpotKind.Instance,
+                                meshName: ready.ownerMeshName,
+                                stableType: ready.stableType
+                            };
+                        }
                         throw new Errors_1.ZLinkFrameworkException(Errors_1.ZLinkFrameworkErrorKind.Unavailable, `SPOT '${spotId}' Ready authority owner lease is unavailable.`);
                     }
                     const target = {

package/dist/runtime/messaging/submission-result.d.ts

@@ -10,7 +10,7 @@ export declare enum ZLinkSubmitStatus {
 export interface ZLinkSubmitResult {
     readonly status: ZLinkSubmitStatus;
 }
-/** Projects immediate refusal and pending admission failure from their Core phase. */
+/** Projects typed submit failure; capacity refusal has no admission wait token. */
 export declare function submitToRequestResult(result: number, phase: 'submit' | 'completion'): number;
 export declare function classifySubmitResult(result: number, operation: string, phase?: 'submit' | 'completion'): ZLinkSubmitResult;
 export declare function requireOneWayCompletion(result: ZLinkSubmitResult, operation: string, notFoundKind?: ZLinkFrameworkInternalErrorKind): void;

package/dist/runtime/messaging/submission-result.js

@@ -19,13 +19,13 @@ var ZLinkSubmitStatus;
     ZLinkSubmitStatus["RouteNotConnected"] = "routeNotConnected";
     ZLinkSubmitStatus["Shutdown"] = "shutdown";
 })(ZLinkSubmitStatus || (exports.ZLinkSubmitStatus = ZLinkSubmitStatus = {}));
-/** Projects immediate refusal and pending admission failure from their Core phase. */
+/** Projects typed submit failure; capacity refusal has no admission wait token. */
 function submitToRequestResult(result, phase) {
     switch (result) {
         case runtime_values_1.SubmitResult.Ok:
             return runtime_values_1.RequestResult.Ok;
         case runtime_values_1.SubmitResult.Backpressured:
-            return phase === 'submit' ? runtime_values_1.RequestResult.NotConnected : runtime_values_1.RequestResult.TimedOut;
+            return runtime_values_1.RequestResult.NotConnected;
         case runtime_values_1.SubmitResult.NotConnected:
             return runtime_values_1.RequestResult.NotConnected;
         case runtime_values_1.SubmitResult.NotFound:

package/dist/runtime/spots/formal-remote-actor-admission-registry.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId } from '../../contracts';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import type { ZLinkDeferredJoinCompletion } from '../actors/deferred-join-completion';
@@ -10,6 +11,7 @@ import type { ZLinkActorRequestTerminal } from './spot-actor-packet-dispatch';
  * how long the underlying buffer stays valid.
  */
 export interface ZLinkParkedActorArrival {
+    readonly origin: ApplicationJobOrigin;
     readonly header: Buffer;
     readonly payload: Buffer;
     readonly returnResponse: boolean;

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, Type, ZLinkMessageSerializer, ZLinkInstanceSpot, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkSpot, ZLinkSpotActorJoinResult, ZLinkSpotInfo, ZLinkSpotPublisherClient } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandlerRegistration, ZLinkSpotPacketHandlerRegistration, ZLinkSpotSubscriptionHandlerRegistration, ZLinkSpotTimerHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
@@ -55,7 +56,7 @@ export interface ZLinkSpotManagerOptions {
     readonly entrySpotCallbacks?: {
         onLeaveActor(actor: ZLinkActor, signal?: AbortSignal, actorRef?: ActorRef, membershipEpoch?: bigint): Promise<void>;
     };
-    readonly dispatchEntryActorPacket?: (actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin) => Promise<unknown>;
+    readonly dispatchEntryActorPacket?: (origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin) => Promise<unknown>;
     /**
      * Commits a stateful MeshNode Actor return to the Entry Spot after the
      * stateful reply has committed Core membership.
@@ -200,7 +201,7 @@ export declare class DefaultZLinkSpotManager {
     beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     cancelActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     notifyJoinedSpotActorDisconnected(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<boolean>;
-    dispatchRoutedActorPacket(spotId: RoutingId, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<unknown>;
+    dispatchRoutedActorPacket(origin: ApplicationJobOrigin, spotId: RoutingId, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<unknown>;
     dispatchRoutedSpotSend(spotId: RoutingId, packetName: string | undefined, message: unknown, context: {
         readonly channelName: string;
         readonly contentType?: string;
@@ -220,7 +221,7 @@ export declare class DefaultZLinkSpotManager {
     dispatchMeshInstance(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private reportInstanceDispatchFailure;
     private traceInstanceMessage;
-    dispatchMeshActor(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
+    dispatchMeshActor(origin: ApplicationJobOrigin, meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     dispatchMeshActorJoin(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private dispatchMeshActorJoinCore;
     dispatchMeshSpotControl(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;

package/dist/runtime/spots/index.js

@@ -860,20 +860,20 @@ class DefaultZLinkSpotManager {
     async notifyJoinedSpotActorDisconnected(spotId, actor, signal) {
         return await this.actorMembership.notifyJoinedActorDisconnected(spotId, actor, signal);
     }
-    dispatchRoutedActorPacket(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+    dispatchRoutedActorPacket(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
         const activation = this.activations.resolveUnique(spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
         }
-        return this.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+        return this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
     }
     /** @internal Replays a record already owned by the Actor handoff queue. */
-    dispatchRoutedActorPacketDirect(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+    dispatchRoutedActorPacketDirect(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
         const activation = this.activations.resolveUnique(spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
         }
-        return this.activationLifecycle.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+        return this.activationLifecycle.dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
     }
     /** @internal Atomically restores one durable packet prefix to an Actor FIFO. */
     admitRoutedActorPacketPrefix(spotId, actorId, records) {
@@ -1071,7 +1071,7 @@ class DefaultZLinkSpotManager {
             errorReason
         });
     }
-    async dispatchMeshActor(meshName, owner, record) {
+    async dispatchMeshActor(origin, meshName, owner, record) {
         const spotId = owner.spotId;
         const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
         const targetsEntrySpot = spotId === null || (entrySpotId !== undefined && spotId === entrySpotId);
@@ -1115,8 +1115,8 @@ class DefaultZLinkSpotManager {
                 throw new Error(`Actor '${actor.actorId}' target transfer reconciliation is not complete.`);
             }
             const response = targetsEntrySpot
-                ? await this.options.dispatchEntryActorPacket?.(actor.actorId, record.parts, request, undefined, ownerActorRef, requestTerminal, record.messageFollowOrigin)
-                : await this.dispatchMeshActorPacket(meshName, spotId, actor.actorId, record.parts, request, ownerActorRef, requestTerminal, record.messageFollowOrigin);
+                ? await this.options.dispatchEntryActorPacket?.(origin, actor.actorId, record.parts, request, undefined, ownerActorRef, requestTerminal, record.messageFollowOrigin)
+                : await this.dispatchMeshActorPacket(origin, meshName, spotId, actor.actorId, record.parts, request, ownerActorRef, requestTerminal, record.messageFollowOrigin);
             if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
                 throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot Actor dispatch is not configured.');
             }
@@ -1631,7 +1631,7 @@ class DefaultZLinkSpotManager {
                                 if (this.options.dispatchEntryActorPacket === undefined) {
                                     throw new Error('Entry Spot saved handoff replay requires its Actor packet runtime.');
                                 }
-                                return await this.options.dispatchEntryActorPacket(entryActor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+                                return await this.options.dispatchEntryActorPacket('remote', entryActor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
                             }, (index) => this.options.runtimeEventPublisher?.publish({
                                 sourceName: 'zlink.framework.actor-handoff',
                                 timestamp: new Date(),
@@ -1790,7 +1790,7 @@ class DefaultZLinkSpotManager {
                 };
                 const completeTargetReady = async () => {
                     if (pendingTransfer !== undefined) {
-                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket(activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
+                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket('remote', activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
                             sourceName: 'zlink.framework.actor-handoff',
                             timestamp: new Date(),
                             marker: 'backlog_enqueued',
@@ -2033,8 +2033,8 @@ class DefaultZLinkSpotManager {
             throw new configuration_1.ZLinkConfigurationException('Spot type is not registered as a spot factory.');
         }
     }
-    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
-        return await this.activationLifecycle.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    async dispatchActorPacket(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        return await this.activationLifecycle.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
     /**
      * Spec 15 §4.2 relocation temporary queue: drains every arrival parked
@@ -2050,7 +2050,7 @@ class DefaultZLinkSpotManager {
         const drained = this.formalRemoteActorAdmissions.completeMigration(transferId);
         for (const arrival of drained) {
             try {
-                const response = await this.dispatchActorPacket(activation, actor.context.actorId, [runtime_message_1.ZLinkBufferMessage.from(arrival.header), runtime_message_1.ZLinkBufferMessage.from(arrival.payload)], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
+                const response = await this.dispatchActorPacket(arrival.origin, activation, actor.context.actorId, [runtime_message_1.ZLinkBufferMessage.from(arrival.header), runtime_message_1.ZLinkBufferMessage.from(arrival.payload)], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
                 arrival.resolve(response);
             }
             catch (error) {
@@ -2058,12 +2058,12 @@ class DefaultZLinkSpotManager {
             }
         }
     }
-    async dispatchMeshActorPacket(meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+    async dispatchMeshActorPacket(origin, meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         const activation = this.activations.resolve(meshName, spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${String(spotId)}' is not active in mesh '${meshName}'.`);
         }
-        return await this.dispatchActorPacket(activation, actorId, parts, returnResponse, undefined, fallbackActorRef, requestTerminal, messageFollowOrigin);
+        return await this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, undefined, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
 }
 exports.DefaultZLinkSpotManager = DefaultZLinkSpotManager;

package/dist/runtime/spots/spot-activation.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, Type, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkMessageSerializer, ZLinkInstanceSpot, ZLinkSpot, ZLinkSpotPublisherClient } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkRuntimeAdmissionGate } from '../admission';
@@ -82,7 +83,7 @@ export declare class ZLinkSpotActivationLifecycle {
     /** Returns the OnClosing failure, which cleanup records and does not rethrow. */
     cleanupClosedActivation(activation: ZLinkSpotActivation, reason?: ZLinkSpotCloseReason, deadline?: Date): Promise<unknown>;
     cleanupFailedIncarnation(activation: ZLinkSpotActivation): Promise<void>;
-    dispatchActorPacket(activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    dispatchActorPacket(origin: ApplicationJobOrigin, activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     private runCreateLifecycle;
     private cleanupActivation;
     private runCleanup;