@zlink-systems/framework 0.10.0

package/dist/runtime/locations/resolvers.js

@@ -0,0 +1,693 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkAuthoritySpotRouteResolver = exports.ZLinkLocationSpotRouteResolver = exports.DefaultZLinkLocationReadiness = exports.ZLinkStoreLocationResolvers = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const internal_location_contracts_1 = require("./internal-location-contracts");
+const service_authority_payload_codec_1 = require("../foundation/service-authority-payload-codec");
+const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const actor_authority_publication_1 = require("../actors/actor-authority-publication");
+const authority_key_codec_1 = require("./authority-key-codec");
+const Spots_1 = require("../../contracts/Spots");
+const Errors_1 = require("../../contracts/Errors");
+const spot_handle_1 = require("../spots/spot-handle");
+const canonical_codec_1 = require("./canonical-codec");
+const lease_tracker_1 = require("./lease-tracker");
+const routing_id_1 = require("../routing-id");
+const state_lane_1 = require("../execution/state-lane");
+const diagnostics_1 = require("../diagnostics");
+/**
+ * Authority payloads are writer-private.  The active outer row is the
+ * cross-language route contract when a foreign writer's payload cannot be
+ * decoded by this runtime.
+ */
+function projectCanonicalActorRoute(snapshot, actorId) {
+    const { allocation } = snapshot;
+    const nodeRid = allocation.descriptor.rid;
+    if (allocation.objectKind !== 'actor'
+        || allocation.state !== 'active'
+        || snapshot.objectGeneration <= 0n
+        || snapshot.ownerLeaseGeneration <= 0n
+        || actorId.length === 0
+        || allocation.stableType.length === 0
+        || allocation.descriptor.meshName.length === 0
+        || String(nodeRid).length === 0
+        || allocation.descriptorLifecycleGeneration <= 0n)
+        return undefined;
+    return {
+        meshName: allocation.descriptor.meshName,
+        actorRef: {
+            actorId,
+            objectGeneration: snapshot.objectGeneration,
+            meshName: allocation.descriptor.meshName,
+            nodeRid
+        },
+        actorType: allocation.stableType,
+        ownerNodeGeneration: allocation.descriptorLifecycleGeneration,
+        ownerId: snapshot.ownerId,
+        ownerLeaseGeneration: snapshot.ownerLeaseGeneration,
+        authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+        authorityStoreVersion: snapshot.storeVersion.value
+    };
+}
+class ZLinkStoreLocationResolvers {
+    options;
+    lane = new state_lane_1.ZLinkStateLane();
+    liveRows;
+    monotonicNowMs;
+    actorRoutes = new Map();
+    directActorRoutes = new Map();
+    spotRoutes = new Map();
+    authoritySpotResolver;
+    nextActorPlacement = 0n;
+    constructor(options) {
+        this.options = options;
+        this.liveRows = new lease_tracker_1.ZLinkLiveRowFilter(options.leaseTracker);
+        this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+        this.authoritySpotResolver = new ZLinkAuthoritySpotRouteResolver(options.stores.authorityStore, (meshName) => meshName, undefined, options.leaseTracker, options.routeCacheMaxAgeMs, this.monotonicNowMs);
+    }
+    async listLivePeers(filter, signal) {
+        const rows = await this.options.stores.peerStore.listPeers(filter, signal);
+        return await this.liveRows.filter(rows, (row) => row.ownerId, signal, (row) => (0, canonical_codec_1.isKnownZLinkLocationAutoConnectType)(row.autoConnectType) && (0, canonical_codec_1.isKnownZLinkLocationRole)(row.role));
+    }
+    async resolveEntrySpotNode(spotId, meshNames, signal) {
+        for (const meshName of meshNames) {
+            const descriptors = await this.liveRows.filter((await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items, (descriptor) => descriptor.ownerId, signal);
+            const descriptor = descriptors.find((candidate) => candidate.entrySpotId === spotId
+                && candidate.objectRole === internal_location_contracts_1.ZLinkObjectRole.Server
+                // An Entry Spot accepts new joins only while its owning node is Serving.
+                // Preparing/retiring/error rows may still be visible during replacement,
+                // but routing them would turn a valid transfer into NotConnected.
+                && candidate.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Serving);
+            if (descriptor !== undefined) {
+                return {
+                    meshName,
+                    nodeRid: descriptor.rid,
+                    spotId,
+                    targetNodeGeneration: descriptor.lifecycleGeneration,
+                    targetOwnerId: descriptor.ownerId,
+                    ownerLeaseGeneration: descriptor.leaseGeneration
+                };
+            }
+        }
+        return undefined;
+    }
+    async selectActorPlacement(meshName, actorType, excludedNodeRid, signal, excludedCandidateRids = new Set()) {
+        const descriptors = (await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items;
+        const liveDescriptors = await this.liveRows.filter(descriptors, (descriptor) => descriptor.ownerId, signal);
+        const candidates = liveDescriptors.filter((descriptor) => {
+            const capacity = descriptor.populationCapacity.actors;
+            return descriptor.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Serving
+                && descriptor.objectRole === internal_location_contracts_1.ZLinkObjectRole.Server
+                && descriptor.placementWeight > 0
+                && !(0, routing_id_1.routingIdsEqual)(descriptor.rid, excludedNodeRid)
+                && !excludedCandidateRids.has(String(descriptor.rid))
+                && capacity.active + capacity.reserved < capacity.limit
+                && descriptor.objectCapabilities.some((candidate) => candidate.objectKind === 'actor' && candidate.stableType === actorType);
+        });
+        if (candidates.length === 0)
+            return undefined;
+        const totalWeight = candidates.reduce((total, candidate) => total + BigInt(candidate.placementWeight), 0n);
+        let ticket = await this.lane.run(() => this.takeActorPlacementTicket(totalWeight));
+        for (const candidate of candidates) {
+            const weight = BigInt(candidate.placementWeight);
+            if (ticket < weight)
+                return candidate.rid;
+            ticket -= weight;
+        }
+        return candidates[candidates.length - 1]?.rid;
+    }
+    async resolveRoute(key, signal) {
+        const row = await this.liveRows.resolve(await this.options.stores.routeStore.resolveRoute(key, signal), (candidate) => candidate.ownerId, signal);
+        if (row === undefined) {
+            this.options.events?.routeResolveMiss(key);
+            return undefined;
+        }
+        return row;
+    }
+    async resolveSpotRef(meshName, spotId, signal) {
+        const row = await this.resolveSpotRow({ meshName, spotId }, signal);
+        if (row !== undefined) {
+            if (row.spotGeneration <= 0n) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `SPOT '${spotId}' location row has no valid Core lifecycle generation.`);
+            }
+            return {
+                meshName: row.meshName,
+                nodeRid: String(row.ownerNodeRid),
+                spotId: String(row.spotId),
+                spotKind: row.spotKind,
+                spotGeneration: row.spotGeneration,
+                targetNodeState: await this.resolveMeshNodeState(row.meshName, row.ownerNodeRid, row.ownerNodeGeneration, signal)
+            };
+        }
+        const entrySpot = await resolveEntrySpotPeerInMeshes(this, spotId, [meshName], signal);
+        if (entrySpot !== undefined) {
+            return {
+                meshName: entrySpot.meshName,
+                nodeRid: String(entrySpot.nodeRid),
+                spotId: entrySpot.spotId,
+                spotKind: Spots_1.ZLinkSpotKind.Entry,
+                targetNodeState: internal_location_contracts_1.ZLinkFrameworkRuntimeState.Serving
+            };
+        }
+        return undefined;
+    }
+    async resolveSpotHandle(meshName, spotId, signal) {
+        const initial = await this.resolveSpotRef(meshName, spotId, signal);
+        if (initial === undefined)
+            return undefined;
+        return (0, spot_handle_1.createSpotHandle)(String(spotId), initial, (refreshSignal) => this.resolveSpotRef(meshName, spotId, refreshSignal));
+    }
+    async resolveActorSpotRef(meshName, actorId, signal) {
+        const row = await this.resolveActorRow({ meshName, actorId }, signal);
+        if (row === undefined) {
+            return undefined;
+        }
+        const spotId = row.spotKind === Spots_1.ZLinkSpotKind.Entry
+            ? row.ownerNodeRid
+            : row.spotId;
+        return {
+            meshName: row.meshName,
+            nodeRid: String(row.ownerNodeRid),
+            spotId: String(spotId),
+            spotKind: row.spotKind,
+            spotGeneration: row.spotGeneration
+        };
+    }
+    async resolveActorRef(actorId, signal) {
+        const direct = await this.resolveDirectActorRoute(actorId, signal);
+        if (direct.kind === 'ready') {
+            return {
+                ...direct.route.actorRef,
+                ownershipGeneration: direct.route.authorityOwnerGeneration,
+                ownerLeaseGeneration: direct.route.ownerLeaseGeneration
+            };
+        }
+        if (direct.kind === 'owner_unavailable')
+            return undefined;
+        // An authority row is the canonical Actor location. If it exists but is
+        // not active or its owner lease is expired, the legacy location projection
+        // must not resurrect a stale route while recovery is pending.
+        const authority = await this.options.stores.authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), signal);
+        if (authority.kind === 'snapshot') {
+            return undefined;
+        }
+        return (await this.resolveActorRow({ meshName: '', actorId }, signal))?.actorRef;
+    }
+    async resolveDirectActorRoute(actorId, signal) {
+        const cached = await this.lane.run(() => this.getCachedCore(this.directActorRoutes, actorId));
+        if (cached !== undefined)
+            return { kind: 'ready', route: cached };
+        const current = await this.options.stores.authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), signal);
+        if (current.kind !== 'snapshot' || current.allocation.state !== 'active') {
+            return { kind: 'missing' };
+        }
+        const decoded = (0, actor_authority_publication_1.decodeActorAuthorityIdentity)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(current.payload), current.objectGeneration);
+        const currentOwner = {
+            ownerId: current.ownerId,
+            leaseGeneration: current.ownerLeaseGeneration
+        };
+        const remainingLeaseMs = await this.options.leaseTracker.remainingOwnerTokenLeaseMs(currentOwner, signal);
+        if (remainingLeaseMs <= 0) {
+            const unavailable = {
+                kind: 'owner_unavailable',
+                authorityGeneration: current.authorityOwnerGeneration,
+                remainingLeaseMs
+            };
+            (0, diagnostics_1.emitActorOwnerLeaseObservation)({
+                actorId,
+                authorityGeneration: unavailable.authorityGeneration,
+                remainingLeaseMs,
+                decision: 'owner_unavailable'
+            });
+            return unavailable;
+        }
+        if (decoded === undefined
+            || decoded.actor.actorId !== actorId
+            || decoded.actor.objectGeneration !== current.objectGeneration) {
+            const route = await this.cacheDirectActorRoute(actorId, projectCanonicalActorRoute(current, actorId), remainingLeaseMs);
+            return route === undefined
+                ? { kind: 'missing' }
+                : { kind: 'ready', route };
+        }
+        let enclosingSpotRoute;
+        if (decoded.spotKind === Spots_1.ZLinkSpotKind.User) {
+            try {
+                enclosingSpotRoute = await this.authoritySpotResolver.resolve(decoded.spotId, signal);
+            }
+            catch (error) {
+                if (error instanceof Errors_1.ZLinkFrameworkException
+                    && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound) {
+                    return { kind: 'missing' };
+                }
+                throw error;
+            }
+        }
+        const route = {
+            meshName: current.allocation.descriptor.meshName,
+            actorRef: {
+                ...decoded.actor,
+                meshName: current.allocation.descriptor.meshName,
+                nodeRid: current.allocation.descriptor.rid
+            },
+            actorType: decoded.actorType,
+            ownerNodeGeneration: current.allocation.descriptorLifecycleGeneration,
+            ownerId: currentOwner.ownerId,
+            ownerLeaseGeneration: currentOwner.leaseGeneration,
+            authorityOwnerGeneration: current.authorityOwnerGeneration,
+            authorityStoreVersion: current.storeVersion.value,
+            ...(decoded.spotKind === Spots_1.ZLinkSpotKind.User
+                ? { spotId: decoded.spotId, spotGeneration: decoded.spotGeneration }
+                : {}),
+            enclosingSpotRoute
+        };
+        const cachedRoute = await this.cacheDirectActorRoute(actorId, route, remainingLeaseMs);
+        return cachedRoute === undefined
+            ? { kind: 'missing' }
+            : { kind: 'ready', route: cachedRoute };
+    }
+    async cacheDirectActorRoute(actorId, route, remainingLeaseMs) {
+        return await this.lane.run(() => {
+            if (route === undefined)
+                return undefined;
+            const maxAgeMs = this.options.routeCacheMaxAgeMs ?? 15000;
+            if (maxAgeMs > 0) {
+                this.directActorRoutes.set(actorId, {
+                    row: route,
+                    expiresAtMs: this.monotonicNowMs() + Math.min(maxAgeMs, remainingLeaseMs),
+                    storeVersion: route.authorityStoreVersion
+                });
+            }
+            return route;
+        });
+    }
+    observeActorAuthorityVersion(actorId, storeVersion) {
+        const cached = this.directActorRoutes.get(actorId);
+        if (cached !== undefined && cached.storeVersion !== storeVersion) {
+            this.directActorRoutes.delete(actorId);
+        }
+    }
+    async resolveActorSpotHandle(meshName, actorId, signal) {
+        const initial = await this.resolveActorSpotRef(meshName, actorId, signal);
+        if (initial === undefined)
+            return undefined;
+        return (0, spot_handle_1.createSpotHandle)(initial.spotId, initial, (refreshSignal) => this.resolveActorSpotRef(meshName, actorId, refreshSignal));
+    }
+    async resolveSpotRow(key, signal) {
+        const cacheKey = `${key.meshName}\u0000${String(key.spotId)}`;
+        const cached = await this.lane.run(() => this.getCachedCore(this.spotRoutes, cacheKey));
+        if (cached !== undefined)
+            return cached;
+        const row = await this.liveRows.resolve(await this.options.stores.spotStore.resolveSpot(key, signal), (candidate) => candidate.ownerId, signal);
+        if (row === undefined) {
+            this.options.events?.spotResolveMiss(key);
+            return undefined;
+        }
+        if (!await this.cacheReady(this.spotRoutes, cacheKey, row, row.ownerId, row.leaseGeneration, signal)) {
+            this.options.events?.spotResolveMiss(key);
+            return undefined;
+        }
+        return row;
+    }
+    async resolveSpotRowInMeshes(spotId, meshNames, signal) {
+        for (const meshName of meshNames) {
+            const row = await this.resolveSpotRow({ meshName, spotId }, signal);
+            if (row !== undefined) {
+                return row;
+            }
+        }
+        return undefined;
+    }
+    async resolveMeshNodeState(meshName, nodeRid, expectedLifecycleGeneration, signal) {
+        const descriptor = (await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items.find((candidate) => (0, routing_id_1.routingIdsEqual)(candidate.rid, nodeRid)
+            && (expectedLifecycleGeneration === undefined
+                || candidate.lifecycleGeneration === expectedLifecycleGeneration));
+        return descriptor?.state;
+    }
+    async resolveActorRow(key, signal) {
+        const cacheKey = `${key.meshName}\u0000${key.actorId}`;
+        const cached = await this.lane.run(() => this.getCachedCore(this.actorRoutes, cacheKey));
+        if (cached !== undefined)
+            return cached;
+        const meshNames = key.meshName.length === 0
+            ? this.options.spotMeshNames ?? []
+            : [key.meshName];
+        let stored;
+        for (const meshName of meshNames) {
+            stored = await this.options.stores.actorStore.resolveActor({
+                meshName,
+                actorId: key.actorId
+            }, signal);
+            if (stored !== undefined)
+                break;
+        }
+        const row = await this.liveRows.resolve(stored, (candidate) => candidate.ownerId, signal, (candidate) => candidate.actorRef.objectGeneration > 0n
+            && candidate.ownerNodeGeneration > 0n
+            && candidate.membershipEpoch > 0n);
+        if (row === undefined) {
+            this.options.events?.actorResolveMiss(key);
+            return undefined;
+        }
+        if (!await this.cacheReady(this.actorRoutes, cacheKey, row, row.ownerId, row.leaseGeneration, signal)) {
+            this.options.events?.actorResolveMiss(key);
+            return undefined;
+        }
+        return row;
+    }
+    invalidateActorRoute(actorId, meshName = '') {
+        this.directActorRoutes.delete(actorId);
+        if (meshName.length > 0) {
+            this.actorRoutes.delete(`${meshName}\u0000${actorId}`);
+            return;
+        }
+        for (const key of this.actorRoutes.keys()) {
+            if (key.endsWith(`\u0000${actorId}`))
+                this.actorRoutes.delete(key);
+        }
+    }
+    invalidateActorRouteIfMatches(fence) {
+        let invalidated = false;
+        const direct = this.directActorRoutes.get(fence.actorId);
+        if (direct !== undefined && directActorRouteMatchesFence(direct.row, fence)) {
+            this.directActorRoutes.delete(fence.actorId);
+            invalidated = true;
+        }
+        for (const [key, cached] of this.actorRoutes) {
+            if (legacyActorRouteMatchesFence(cached.row, fence)) {
+                this.actorRoutes.delete(key);
+                invalidated = true;
+            }
+        }
+        return invalidated;
+    }
+    invalidateSpotRoute(spotId, meshName) {
+        if (meshName !== undefined) {
+            this.spotRoutes.delete(`${meshName}\u0000${spotId}`);
+        }
+        else {
+            for (const key of this.spotRoutes.keys()) {
+                if (key.endsWith(`\u0000${spotId}`))
+                    this.spotRoutes.delete(key);
+            }
+        }
+        for (const [key, cached] of this.actorRoutes) {
+            if (cached.row.spotId === spotId
+                && (meshName === undefined || cached.row.meshName === meshName))
+                this.actorRoutes.delete(key);
+        }
+    }
+    invalidateSpotRouteIfMatches(fence) {
+        let invalidated = false;
+        for (const [key, cached] of this.spotRoutes) {
+            if (spotRouteMatchesFence(cached.row, fence)) {
+                this.spotRoutes.delete(key);
+                invalidated = true;
+            }
+        }
+        for (const [key, cached] of this.actorRoutes) {
+            if (actorEnclosingSpotMatchesFence(cached.row, fence)) {
+                this.actorRoutes.delete(key);
+                invalidated = true;
+            }
+        }
+        for (const [key, cached] of this.directActorRoutes) {
+            if (resolvedActorEnclosingSpotMatchesFence(cached.row, fence)) {
+                this.directActorRoutes.delete(key);
+                invalidated = true;
+            }
+        }
+        return invalidated;
+    }
+    takeActorPlacementTicket(totalWeight) {
+        const ticket = this.nextActorPlacement % totalWeight;
+        this.nextActorPlacement++;
+        return ticket;
+    }
+    getCachedCore(cache, key) {
+        const entry = cache.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (this.monotonicNowMs() >= entry.expiresAtMs) {
+            cache.delete(key);
+            return undefined;
+        }
+        return entry.row;
+    }
+    async cacheReady(cache, key, row, ownerId, ownerLeaseGeneration, signal) {
+        const maxAgeMs = this.options.routeCacheMaxAgeMs ?? 15000;
+        const remainingLeaseMs = await this.options.leaseTracker.remainingOwnerTokenLeaseMs({ ownerId, leaseGeneration: ownerLeaseGeneration }, signal);
+        if (remainingLeaseMs <= 0)
+            return false;
+        if (maxAgeMs <= 0)
+            return true;
+        const lifetimeMs = Math.min(maxAgeMs, remainingLeaseMs);
+        if (lifetimeMs <= 0)
+            return false;
+        return await this.lane.run(() => {
+            cache.set(key, { row, expiresAtMs: this.monotonicNowMs() + lifetimeMs });
+            return true;
+        });
+    }
+}
+exports.ZLinkStoreLocationResolvers = ZLinkStoreLocationResolvers;
+function directActorRouteMatchesFence(route, fence) {
+    return route.actorRef.actorId === fence.actorId
+        && route.actorRef.objectGeneration === fence.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(route.actorRef.nodeRid, fence.targetNodeRid)
+        && route.ownerNodeGeneration === fence.targetNodeGeneration
+        && route.authorityOwnerGeneration === fence.authorityOwnerGeneration
+        && route.ownerLeaseGeneration === fence.ownerLeaseGeneration;
+}
+function legacyActorRouteMatchesFence(route, fence) {
+    return route.actorId === fence.actorId
+        && route.actorRef.objectGeneration === fence.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(route.actorRef.nodeRid, fence.targetNodeRid)
+        && route.ownerNodeGeneration === fence.targetNodeGeneration
+        && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+function spotRouteMatchesFence(route, fence) {
+    return route.spotId === fence.spotId
+        && route.spotGeneration === fence.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(route.ownerNodeRid, fence.targetNodeRid)
+        && route.ownerNodeGeneration === fence.targetNodeGeneration
+        && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+function actorEnclosingSpotMatchesFence(route, fence) {
+    return route.spotId === fence.spotId
+        && route.spotGeneration === fence.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(route.ownerNodeRid, fence.targetNodeRid)
+        && route.ownerNodeGeneration === fence.targetNodeGeneration
+        && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+function resolvedActorEnclosingSpotMatchesFence(route, fence) {
+    const enclosing = route.enclosingSpotRoute;
+    return enclosing !== undefined
+        && enclosing.spotId === fence.spotId
+        && enclosing.targetSpotGeneration === fence.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(enclosing.targetNodeRid, fence.targetNodeRid)
+        && enclosing.targetNodeGeneration === fence.targetNodeGeneration
+        && enclosing.authorityOwnerGeneration === fence.authorityOwnerGeneration
+        && enclosing.ownerLeaseGeneration === fence.ownerLeaseGeneration;
+}
+class DefaultZLinkLocationReadiness {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    async isPeerReady(meshName, role, nodeRid, signal) {
+        try {
+            void role;
+            const page = await this.query.listTopology({
+                meshName,
+                nodeRid,
+                state: internal_location_contracts_1.ZLinkLocationTopologyState.Ready
+            }, undefined, signal);
+            return page.items.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.DefaultZLinkLocationReadiness = DefaultZLinkLocationReadiness;
+class ZLinkLocationSpotRouteResolver {
+    rows;
+    meshNames;
+    routerChannelIdForMesh;
+    resolveLocalSpot;
+    constructor(rows, meshNames, routerChannelIdForMesh = (meshName) => meshName, resolveLocalSpot) {
+        this.rows = rows;
+        this.meshNames = meshNames;
+        this.routerChannelIdForMesh = routerChannelIdForMesh;
+        this.resolveLocalSpot = resolveLocalSpot;
+    }
+    async resolve(spotId, signal) {
+        const row = await this.rows.resolveSpotRowInMeshes(spotId, this.meshNames, signal);
+        if (row !== undefined) {
+            if (row.spotGeneration <= 0n) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `SPOT '${spotId}' location row has no valid Core lifecycle generation.`);
+            }
+            return {
+                routerChannelId: this.routerChannelIdForMesh(row.meshName),
+                targetNodeRid: row.ownerNodeRid,
+                spotId: row.spotId,
+                spotKind: row.spotKind,
+                targetSpotGeneration: row.spotGeneration,
+                ownerLeaseGeneration: row.leaseGeneration,
+                targetNodeState: await this.rows.resolveMeshNodeState(row.meshName, row.ownerNodeRid, row.ownerNodeGeneration, signal)
+            };
+        }
+        const local = this.resolveLocalSpot?.(spotId);
+        if (local !== undefined) {
+            return local;
+        }
+        const entrySpot = await resolveEntrySpotPeerInMeshes(this.rows, spotId, this.meshNames, signal);
+        if (entrySpot !== undefined) {
+            return {
+                routerChannelId: this.routerChannelIdForMesh(entrySpot.meshName),
+                targetNodeRid: entrySpot.nodeRid,
+                spotId: entrySpot.spotId,
+                spotKind: Spots_1.ZLinkSpotKind.Entry,
+                targetNodeGeneration: entrySpot.targetNodeGeneration,
+                targetOwnerId: entrySpot.targetOwnerId,
+                ownerLeaseGeneration: entrySpot.ownerLeaseGeneration,
+                targetNodeState: internal_location_contracts_1.ZLinkFrameworkRuntimeState.Serving
+            };
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `SPOT '${spotId}' has no live location row in any registered spot mesh.`);
+    }
+    invalidate(spotId) {
+        this.rows.invalidateSpotRoute(String(spotId));
+    }
+}
+exports.ZLinkLocationSpotRouteResolver = ZLinkLocationSpotRouteResolver;
+class ZLinkAuthoritySpotRouteResolver {
+    store;
+    routerChannelIdForMesh;
+    fallback;
+    leaseTracker;
+    routeCacheMaxAgeMs;
+    monotonicNowMs;
+    targetNodeStateResolver;
+    lane = new state_lane_1.ZLinkStateLane();
+    cache = new Map();
+    routeEpochs = new Map();
+    activeResolutions = new Map();
+    constructor(store, routerChannelIdForMesh, fallback, leaseTracker, routeCacheMaxAgeMs = 15000, monotonicNowMs = () => performance.now(), targetNodeStateResolver) {
+        this.store = store;
+        this.routerChannelIdForMesh = routerChannelIdForMesh;
+        this.fallback = fallback;
+        this.leaseTracker = leaseTracker;
+        this.routeCacheMaxAgeMs = routeCacheMaxAgeMs;
+        this.monotonicNowMs = monotonicNowMs;
+        this.targetNodeStateResolver = targetNodeStateResolver;
+    }
+    async resolve(spotId, signal) {
+        const key = String(spotId);
+        const prepared = await this.lane.run(() => this.beginResolutionCore(key));
+        try {
+            if (prepared.cached !== undefined)
+                return prepared.cached;
+            const current = await this.store.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('user_spot', key), signal);
+            if (current.kind === 'snapshot' && current.allocation.state === 'active') {
+                const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)((0, service_relocation_runtime_1.serviceRelocationAuthorityApplicationPayload)(current.payload));
+                if (decoded !== undefined
+                    && decoded.spotId === String(spotId)
+                    && decoded.ownerId === current.ownerId
+                    && decoded.ownerLeaseGeneration === current.ownerLeaseGeneration) {
+                    const remainingLeaseMs = this.leaseTracker === undefined
+                        ? undefined
+                        : await this.leaseTracker.remainingOwnerTokenLeaseMs({
+                            ownerId: current.ownerId,
+                            leaseGeneration: current.ownerLeaseGeneration
+                        }, signal);
+                    if (remainingLeaseMs !== undefined && remainingLeaseMs <= 0) {
+                        throw new Errors_1.ZLinkFrameworkException(Errors_1.ZLinkFrameworkErrorKind.Unavailable, `SPOT '${spotId}' Ready authority owner lease is unavailable.`);
+                    }
+                    const target = {
+                        routerChannelId: this.routerChannelIdForMesh(decoded.ownerMeshName),
+                        targetNodeRid: decoded.ownerNodeRid,
+                        spotId,
+                        spotKind: decoded.kind === 'instance_spot'
+                            ? Spots_1.ZLinkSpotKind.Instance
+                            : Spots_1.ZLinkSpotKind.User,
+                        stableType: decoded.stableType,
+                        targetSpotGeneration: current.objectGeneration,
+                        targetNodeGeneration: current.allocation.descriptorLifecycleGeneration,
+                        authorityOwnerGeneration: current.authorityOwnerGeneration,
+                        targetOwnerId: current.ownerId,
+                        ownerLeaseGeneration: current.ownerLeaseGeneration,
+                        authorityStoreVersion: current.storeVersion.value,
+                        targetNodeState: await this.targetNodeStateResolver?.(decoded.ownerMeshName, decoded.ownerNodeRid, current.allocation.descriptorLifecycleGeneration, signal)
+                    };
+                    await this.lane.run(() => this.cacheResolutionCore(key, prepared.epoch, target, remainingLeaseMs, current.storeVersion.value));
+                    return target;
+                }
+            }
+            if (current.kind === 'snapshot') {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `SPOT '${spotId}' authority has not crossed the Ready barrier.`);
+            }
+            if (this.fallback !== undefined) {
+                return await this.fallback.resolve(spotId, signal);
+            }
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `SPOT '${spotId}' has no Ready authority.`);
+        }
+        finally {
+            await this.lane.run(() => this.finishResolutionCore(key));
+        }
+    }
+    invalidate(spotId) {
+        const key = String(spotId);
+        this.invalidateCore(key);
+        this.fallback?.invalidate?.(spotId);
+    }
+    invalidateCore(key) {
+        this.cache.delete(key);
+        if (this.activeResolutions.has(key)) {
+            this.routeEpochs.set(key, this.currentEpochCore(key) + 1);
+        }
+        else {
+            this.routeEpochs.delete(key);
+        }
+    }
+    beginResolutionCore(key) {
+        const epoch = this.currentEpochCore(key);
+        this.routeEpochs.set(key, epoch);
+        this.activeResolutions.set(key, (this.activeResolutions.get(key) ?? 0) + 1);
+        const cached = this.cache.get(key);
+        if (cached === undefined)
+            return { epoch };
+        if (this.monotonicNowMs() < cached.expiresAtMs)
+            return { epoch, cached: cached.row };
+        this.cache.delete(key);
+        return { epoch };
+    }
+    cacheResolutionCore(key, epoch, target, remainingLeaseMs, storeVersion) {
+        if (this.routeCacheMaxAgeMs <= 0 || this.currentEpochCore(key) !== epoch)
+            return;
+        const lifetimeMs = Math.min(this.routeCacheMaxAgeMs, remainingLeaseMs ?? 0);
+        if (lifetimeMs <= 0 || this.currentEpochCore(key) !== epoch)
+            return;
+        this.cache.set(key, {
+            row: target,
+            expiresAtMs: this.monotonicNowMs() + lifetimeMs,
+            storeVersion
+        });
+    }
+    finishResolutionCore(key) {
+        const active = this.activeResolutions.get(key);
+        if (active === undefined || active <= 1) {
+            this.activeResolutions.delete(key);
+            if (!this.cache.has(key))
+                this.routeEpochs.delete(key);
+            return;
+        }
+        this.activeResolutions.set(key, active - 1);
+    }
+    currentEpochCore(key) {
+        return this.routeEpochs.get(key) ?? 0;
+    }
+}
+exports.ZLinkAuthoritySpotRouteResolver = ZLinkAuthoritySpotRouteResolver;
+async function resolveEntrySpotPeerInMeshes(rows, spotId, meshNames, signal) {
+    return await rows.resolveEntrySpotNode(spotId, meshNames, signal);
+}