@zlink-systems/framework 0.10.0

package/src/runtime/locations/resolvers.ts

@@ -0,0 +1,1054 @@
+import { ZLinkFrameworkInternalErrorKind, createInternalFrameworkException, internalFrameworkErrorKind  } from '../framework-errors-internal';
+import type { ActorRef, RoutingId, SpotId } from '../../contracts/Common';
+import {
+  ZLinkLocationRole,
+  ZLinkLocationTopologyState,
+  ZLinkFrameworkRuntimeState,
+  ZLinkObjectRole,
+  type ZLinkLocationReadiness,
+  type ZLinkLocationRuntimeQuery,
+  type ZLinkPeerLocationResolver,
+  type ZLinkActorLocation,
+  type ZLinkActorLocationKey,
+  type ZLinkPeerLocation,
+  type ZLinkPeerLocationFilter,
+  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 { decodeServiceReadySpotAuthority } from '../foundation/service-authority-payload-codec';
+import { serviceRelocationAuthorityApplicationPayload } from '../foundation/service-relocation-runtime';
+import { decodeActorAuthorityIdentity } from '../actors/actor-authority-publication';
+import { encodeAuthorityKey } from './authority-key-codec';
+import {
+  ZLinkSpotKind
+} from '../../contracts/Spots';
+import type { ZLinkAuthoritySnapshot } from './internal-location-contracts';
+import type {
+  SpotHandle,
+  ZLinkActorSpotHandleResolver,
+  ZLinkSpotHandleResolver
+} from '../spots/spot-handle';
+import {
+  ZLinkFrameworkErrorKind,
+  ZLinkFrameworkException
+} from '../../contracts/Errors';
+import type {
+  ZLinkSpotRouteResolver,
+  ZLinkSpotRouteTarget
+} from '../spots/spot-routing-internal';
+import { createSpotHandle, type ResolvedSpotHandle } from '../spots/spot-handle';
+import {
+  isKnownZLinkLocationAutoConnectType,
+  isKnownZLinkLocationRole
+} from './canonical-codec';
+import {
+  ZLinkLiveRowFilter,
+  ZLinkOwnerLeaseTracker
+} from './lease-tracker';
+import { routingIdsEqual } from '../routing-id';
+import { ZLinkStateLane } from '../execution/state-lane';
+import { emitActorOwnerLeaseObservation } from '../diagnostics';
+
+export interface ZLinkStoreLocationResolverStores {
+  readonly authorityStore: ZLinkAuthorityStore;
+  readonly locationStore: ZLinkMeshNodeLocationStore;
+  readonly peerStore: ZLinkPeerLocationStore;
+  readonly spotStore: ZLinkSpotLocationStore;
+  readonly actorStore: ZLinkActorLocationStore;
+  readonly routeStore: ZLinkRouteLocationStore;
+}
+
+export interface ZLinkLocationResolverEventSink {
+  spotResolveMiss(key: ZLinkSpotLocationKey): void;
+  actorResolveMiss(key: ZLinkActorLocationKey): void;
+  routeResolveMiss(key: ZLinkRouteLocationKey): void;
+}
+
+export interface ZLinkStoreLocationResolversOptions {
+  readonly stores: ZLinkStoreLocationResolverStores;
+  readonly leaseTracker: ZLinkOwnerLeaseTracker;
+  readonly events?: ZLinkLocationResolverEventSink;
+  readonly spotMeshNames?: readonly string[];
+  readonly routeCacheMaxAgeMs?: number;
+  readonly monotonicNowMs?: () => number;
+}
+
+interface CachedReadyRoute<TRow> {
+  readonly row: TRow;
+  readonly expiresAtMs: number;
+  readonly storeVersion?: string;
+}
+
+/**
+ * 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: ZLinkAuthoritySnapshot,
+  actorId: string
+): ZLinkResolvedActorRoute | undefined {
+  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
+  };
+}
+
+export interface ZLinkResolvedActorRoute {
+  readonly meshName: string;
+  readonly actorRef: ActorRef;
+  readonly actorType: string;
+  readonly ownerNodeGeneration: bigint;
+  readonly ownerId: string;
+  readonly ownerLeaseGeneration: bigint;
+  readonly authorityOwnerGeneration: bigint;
+  readonly authorityStoreVersion: string;
+  readonly spotId?: string;
+  readonly spotGeneration?: bigint;
+  /** Exact enclosing User Spot authority used by remote Actor packet relay. */
+  readonly enclosingSpotRoute?: ZLinkSpotRouteTarget;
+}
+
+export type ZLinkDirectActorRouteResolution =
+  | { readonly kind: 'ready'; readonly route: ZLinkResolvedActorRoute }
+  | { readonly kind: 'missing' }
+  | {
+      readonly kind: 'owner_unavailable';
+      readonly authorityGeneration: bigint;
+      readonly remainingLeaseMs: number;
+    };
+
+export interface ZLinkActorRouteInvalidationFence {
+  readonly actorId: string;
+  readonly objectGeneration: bigint;
+  readonly targetNodeRid: string;
+  readonly targetNodeGeneration: bigint;
+  readonly authorityOwnerGeneration: bigint;
+  readonly ownerLeaseGeneration: bigint;
+}
+
+export interface ZLinkSpotRouteInvalidationFence {
+  readonly spotId: string;
+  readonly objectGeneration: bigint;
+  readonly targetNodeRid: string;
+  readonly targetNodeGeneration: bigint;
+  readonly authorityOwnerGeneration: bigint;
+  readonly ownerLeaseGeneration: bigint;
+}
+
+export class ZLinkStoreLocationResolvers implements
+  ZLinkPeerLocationResolver,
+  ZLinkSpotHandleResolver,
+  ZLinkActorSpotHandleResolver {
+  private readonly lane = new ZLinkStateLane();
+  private readonly liveRows: ZLinkLiveRowFilter;
+  private readonly monotonicNowMs: () => number;
+  private readonly actorRoutes = new Map<string, CachedReadyRoute<ZLinkActorLocation>>();
+  private readonly directActorRoutes = new Map<string, CachedReadyRoute<ZLinkResolvedActorRoute>>();
+  private readonly spotRoutes = new Map<string, CachedReadyRoute<ZLinkSpotLocation>>();
+  private readonly authoritySpotResolver: ZLinkAuthoritySpotRouteResolver;
+  private nextActorPlacement = 0n;
+
+  constructor(private readonly options: ZLinkStoreLocationResolversOptions) {
+    this.liveRows = new 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: ZLinkPeerLocationFilter, signal?: AbortSignal): Promise<readonly ZLinkPeerLocation[]> {
+    const rows = await this.options.stores.peerStore.listPeers(filter, signal);
+    return await this.liveRows.filter(
+      rows,
+      (row) => row.ownerId,
+      signal,
+      (row) => isKnownZLinkLocationAutoConnectType(row.autoConnectType) && isKnownZLinkLocationRole(row.role)
+    );
+  }
+
+  async resolveEntrySpotNode(
+    spotId: SpotId,
+    meshNames: readonly string[],
+    signal?: AbortSignal
+  ): Promise<{
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly spotId: SpotId;
+    readonly targetNodeGeneration: bigint;
+    readonly targetOwnerId: string;
+    readonly ownerLeaseGeneration: bigint;
+  } | undefined> {
+    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 === 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 === 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: string,
+    actorType: string,
+    excludedNodeRid: RoutingId,
+    signal?: AbortSignal,
+    excludedCandidateRids: ReadonlySet<string> = new Set()
+  ): Promise<RoutingId | undefined> {
+    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 === ZLinkFrameworkRuntimeState.Serving
+        && descriptor.objectRole === ZLinkObjectRole.Server
+        && descriptor.placementWeight > 0
+        && !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: ZLinkRouteLocationKey, signal?: AbortSignal): Promise<ZLinkRouteLocation | undefined> {
+    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: string,
+    spotId: RoutingId,
+    signal?: AbortSignal
+  ): Promise<ResolvedSpotHandle | undefined> {
+    const row = await this.resolveSpotRow({ meshName, spotId }, signal);
+    if (row !== undefined) {
+      if (row.spotGeneration <= 0n) {
+        throw createInternalFrameworkException(
+          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: ZLinkSpotKind.Entry,
+        targetNodeState: ZLinkFrameworkRuntimeState.Serving
+      };
+    }
+    return undefined;
+  }
+
+  async resolveSpotHandle(
+    meshName: string,
+    spotId: RoutingId,
+    signal?: AbortSignal
+  ): Promise<SpotHandle | undefined> {
+    const initial = await this.resolveSpotRef(meshName, spotId, signal);
+    if (initial === undefined) return undefined;
+    return createSpotHandle(
+      String(spotId),
+      initial,
+      (refreshSignal) => this.resolveSpotRef(meshName, spotId, refreshSignal)
+    );
+  }
+
+  async resolveActorSpotRef(
+    meshName: string,
+    actorId: string,
+    signal?: AbortSignal
+  ): Promise<ResolvedSpotHandle | undefined> {
+    const row = await this.resolveActorRow({ meshName, actorId }, signal);
+    if (row === undefined) {
+      return undefined;
+    }
+    const spotId = row.spotKind === 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: string, signal?: AbortSignal): Promise<ActorRef | undefined> {
+    const direct = await this.resolveDirectActorRoute(actorId, signal);
+    if (direct.kind === 'ready') {
+      return {
+        ...direct.route.actorRef,
+        ownershipGeneration: direct.route.authorityOwnerGeneration,
+        ownerLeaseGeneration: direct.route.ownerLeaseGeneration
+      } as ActorRef;
+    }
+    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(
+      encodeAuthorityKey('actor', actorId),
+      signal
+    );
+    if (authority.kind === 'snapshot') {
+      return undefined;
+    }
+    return (await this.resolveActorRow({ meshName: '', actorId }, signal))?.actorRef;
+  }
+
+  async resolveDirectActorRoute(
+    actorId: string,
+    signal?: AbortSignal
+  ): Promise<ZLinkDirectActorRouteResolution> {
+    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(
+      encodeAuthorityKey('actor', actorId),
+      signal
+    );
+    if (current.kind !== 'snapshot' || current.allocation.state !== 'active') {
+      return { kind: 'missing' };
+    }
+    const decoded = decodeActorAuthorityIdentity(
+      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' as const,
+        authorityGeneration: current.authorityOwnerGeneration,
+        remainingLeaseMs
+      };
+      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: ZLinkSpotRouteTarget | undefined;
+    if (decoded.spotKind === ZLinkSpotKind.User) {
+      try {
+        enclosingSpotRoute = await this.authoritySpotResolver.resolve(decoded.spotId, signal);
+      } catch (error) {
+        if (
+          error instanceof ZLinkFrameworkException
+          && internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.SpotRouteNotFound
+        ) {
+          return { kind: 'missing' };
+        }
+        throw error;
+      }
+    }
+    const route: ZLinkResolvedActorRoute = {
+      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 === 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 };
+  }
+
+  private async cacheDirectActorRoute(
+    actorId: string,
+    route: ZLinkResolvedActorRoute | undefined,
+    remainingLeaseMs: number
+  ): Promise<ZLinkResolvedActorRoute | undefined> {
+    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: string, storeVersion: string): void {
+    const cached = this.directActorRoutes.get(actorId);
+    if (cached !== undefined && cached.storeVersion !== storeVersion) {
+      this.directActorRoutes.delete(actorId);
+    }
+  }
+
+  async resolveActorSpotHandle(
+    meshName: string,
+    actorId: string,
+    signal?: AbortSignal
+  ): Promise<SpotHandle | undefined> {
+    const initial = await this.resolveActorSpotRef(meshName, actorId, signal);
+    if (initial === undefined) return undefined;
+    return createSpotHandle(
+      initial.spotId,
+      initial,
+      (refreshSignal) => this.resolveActorSpotRef(meshName, actorId, refreshSignal)
+    );
+  }
+
+  async resolveSpotRow(
+    key: ZLinkSpotLocationKey,
+    signal?: AbortSignal
+  ): Promise<ZLinkSpotLocation | undefined> {
+    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: RoutingId,
+    meshNames: readonly string[],
+    signal?: AbortSignal
+  ): Promise<ZLinkSpotLocation | undefined> {
+    for (const meshName of meshNames) {
+      const row = await this.resolveSpotRow({ meshName, spotId }, signal);
+      if (row !== undefined) {
+        return row;
+      }
+    }
+    return undefined;
+  }
+
+  async resolveMeshNodeState(
+    meshName: string,
+    nodeRid: RoutingId,
+    expectedLifecycleGeneration?: bigint,
+    signal?: AbortSignal
+  ): Promise<ZLinkFrameworkRuntimeState | undefined> {
+    const descriptor = (await this.options.stores.locationStore.listMeshNodes(
+      meshName,
+      undefined,
+      signal
+    )).items.find((candidate) =>
+      routingIdsEqual(candidate.rid, nodeRid)
+      && (
+        expectedLifecycleGeneration === undefined
+        || candidate.lifecycleGeneration === expectedLifecycleGeneration
+      )
+    );
+    return descriptor?.state;
+  }
+
+  async resolveActorRow(
+    key: ZLinkActorLocationKey,
+    signal?: AbortSignal
+  ): Promise<ZLinkActorLocation | undefined> {
+    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: ZLinkActorLocation | undefined;
+    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: string, meshName = ''): void {
+    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: ZLinkActorRouteInvalidationFence): boolean {
+    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: SpotId, meshName?: string): void {
+    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: ZLinkSpotRouteInvalidationFence): boolean {
+    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;
+  }
+
+  private takeActorPlacementTicket(totalWeight: bigint): bigint {
+    const ticket = this.nextActorPlacement % totalWeight;
+    this.nextActorPlacement++;
+    return ticket;
+  }
+
+  private getCachedCore<TRow>(
+    cache: Map<string, CachedReadyRoute<TRow>>,
+    key: string
+  ): TRow | undefined {
+    const entry = cache.get(key);
+    if (entry === undefined) return undefined;
+    if (this.monotonicNowMs() >= entry.expiresAtMs) {
+      cache.delete(key);
+      return undefined;
+    }
+    return entry.row;
+  }
+
+  private async cacheReady<TRow>(
+    cache: Map<string, CachedReadyRoute<TRow>>,
+    key: string,
+    row: TRow,
+    ownerId: string,
+    ownerLeaseGeneration: bigint,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    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;
+    });
+  }
+}
+
+function directActorRouteMatchesFence(
+  route: ZLinkResolvedActorRoute,
+  fence: ZLinkActorRouteInvalidationFence
+): boolean {
+  return route.actorRef.actorId === fence.actorId
+    && route.actorRef.objectGeneration === fence.objectGeneration
+    && routingIdsEqual(route.actorRef.nodeRid, fence.targetNodeRid)
+    && route.ownerNodeGeneration === fence.targetNodeGeneration
+    && route.authorityOwnerGeneration === fence.authorityOwnerGeneration
+    && route.ownerLeaseGeneration === fence.ownerLeaseGeneration;
+}
+
+function legacyActorRouteMatchesFence(
+  route: ZLinkActorLocation,
+  fence: ZLinkActorRouteInvalidationFence
+): boolean {
+  return route.actorId === fence.actorId
+    && route.actorRef.objectGeneration === fence.objectGeneration
+    && routingIdsEqual(route.actorRef.nodeRid, fence.targetNodeRid)
+    && route.ownerNodeGeneration === fence.targetNodeGeneration
+    && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+
+function spotRouteMatchesFence(
+  route: ZLinkSpotLocation,
+  fence: ZLinkSpotRouteInvalidationFence
+): boolean {
+  return route.spotId === fence.spotId
+    && route.spotGeneration === fence.objectGeneration
+    && routingIdsEqual(route.ownerNodeRid, fence.targetNodeRid)
+    && route.ownerNodeGeneration === fence.targetNodeGeneration
+    && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+
+function actorEnclosingSpotMatchesFence(
+  route: ZLinkActorLocation,
+  fence: ZLinkSpotRouteInvalidationFence
+): boolean {
+  return route.spotId === fence.spotId
+    && route.spotGeneration === fence.objectGeneration
+    && routingIdsEqual(route.ownerNodeRid, fence.targetNodeRid)
+    && route.ownerNodeGeneration === fence.targetNodeGeneration
+    && route.leaseGeneration === fence.ownerLeaseGeneration;
+}
+
+function resolvedActorEnclosingSpotMatchesFence(
+  route: ZLinkResolvedActorRoute,
+  fence: ZLinkSpotRouteInvalidationFence
+): boolean {
+  const enclosing = route.enclosingSpotRoute;
+  return enclosing !== undefined
+    && enclosing.spotId === fence.spotId
+    && enclosing.targetSpotGeneration === fence.objectGeneration
+    && routingIdsEqual(enclosing.targetNodeRid, fence.targetNodeRid)
+    && enclosing.targetNodeGeneration === fence.targetNodeGeneration
+    && enclosing.authorityOwnerGeneration === fence.authorityOwnerGeneration
+    && enclosing.ownerLeaseGeneration === fence.ownerLeaseGeneration;
+}
+
+export class DefaultZLinkLocationReadiness implements ZLinkLocationReadiness {
+  constructor(private readonly query: ZLinkLocationRuntimeQuery) {}
+
+  async isPeerReady(
+    meshName: string,
+    role: ZLinkLocationRole,
+    nodeRid?: RoutingId,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    try {
+      void role;
+      const page = await this.query.listTopology({
+        meshName,
+        nodeRid,
+        state: ZLinkLocationTopologyState.Ready
+      }, undefined, signal);
+      return page.items.length > 0;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export class ZLinkLocationSpotRouteResolver implements ZLinkSpotRouteResolver {
+  constructor(
+    private readonly rows: ZLinkStoreLocationResolvers,
+    private readonly meshNames: readonly string[],
+    private readonly routerChannelIdForMesh: (meshName: string) => string = (meshName) => meshName,
+    private readonly resolveLocalSpot?: (spotId: RoutingId) => ZLinkSpotRouteTarget | undefined
+  ) {}
+
+  async resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget> {
+    const row = await this.rows.resolveSpotRowInMeshes(spotId, this.meshNames, signal);
+    if (row !== undefined) {
+      if (row.spotGeneration <= 0n) {
+        throw createInternalFrameworkException(
+          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: ZLinkSpotKind.Entry,
+        targetNodeGeneration: entrySpot.targetNodeGeneration,
+        targetOwnerId: entrySpot.targetOwnerId,
+        ownerLeaseGeneration: entrySpot.ownerLeaseGeneration,
+        targetNodeState: ZLinkFrameworkRuntimeState.Serving
+      };
+    }
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.SpotRouteNotFound,
+      `SPOT '${spotId}' has no live location row in any registered spot mesh.`
+    );
+  }
+
+  invalidate(spotId: RoutingId): void {
+    this.rows.invalidateSpotRoute(String(spotId));
+  }
+}
+
+export class ZLinkAuthoritySpotRouteResolver implements ZLinkSpotRouteResolver {
+  private readonly lane = new ZLinkStateLane();
+  private readonly cache = new Map<string, CachedReadyRoute<ZLinkSpotRouteTarget>>();
+  private readonly routeEpochs = new Map<string, number>();
+  private readonly activeResolutions = new Map<string, number>();
+
+  constructor(
+    private readonly store: ZLinkAuthorityStore,
+    private readonly routerChannelIdForMesh: (meshName: string) => string,
+    private readonly fallback?: ZLinkSpotRouteResolver,
+    private readonly leaseTracker?: ZLinkOwnerLeaseTracker,
+    private readonly routeCacheMaxAgeMs = 15000,
+    private readonly monotonicNowMs: () => number = () => performance.now(),
+    private readonly targetNodeStateResolver?: (
+      meshName: string,
+      nodeRid: RoutingId,
+      expectedLifecycleGeneration: bigint,
+      signal?: AbortSignal
+    ) => Promise<ZLinkFrameworkRuntimeState | undefined>
+  ) {}
+
+  async resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget> {
+    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(
+        encodeAuthorityKey('user_spot', key),
+        signal
+      );
+      if (current.kind === 'snapshot' && current.allocation.state === 'active') {
+        const decoded = decodeServiceReadySpotAuthority(
+          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 ZLinkFrameworkException(
+              ZLinkFrameworkErrorKind.Unavailable,
+              `SPOT '${spotId}' Ready authority owner lease is unavailable.`
+            );
+          }
+          const target: ZLinkSpotRouteTarget = {
+            routerChannelId: this.routerChannelIdForMesh(decoded.ownerMeshName),
+            targetNodeRid: decoded.ownerNodeRid,
+            spotId,
+            spotKind: decoded.kind === 'instance_spot'
+              ? ZLinkSpotKind.Instance
+              : 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 createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotRouteNotFound,
+          `SPOT '${spotId}' authority has not crossed the Ready barrier.`
+        );
+      }
+      if (this.fallback !== undefined) {
+        return await this.fallback.resolve(spotId, signal);
+      }
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.SpotRouteNotFound,
+        `SPOT '${spotId}' has no Ready authority.`
+      );
+    } finally {
+      await this.lane.run(() => this.finishResolutionCore(key));
+    }
+  }
+
+  invalidate(spotId: RoutingId): void {
+    const key = String(spotId);
+    this.invalidateCore(key);
+    this.fallback?.invalidate?.(spotId);
+  }
+
+  private invalidateCore(key: string): void {
+    this.cache.delete(key);
+    if (this.activeResolutions.has(key)) {
+      this.routeEpochs.set(key, this.currentEpochCore(key) + 1);
+    } else {
+      this.routeEpochs.delete(key);
+    }
+  }
+
+  private beginResolutionCore(key: string): { readonly epoch: number; readonly cached?: ZLinkSpotRouteTarget } {
+    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 };
+  }
+
+  private cacheResolutionCore(
+    key: string,
+    epoch: number,
+    target: ZLinkSpotRouteTarget,
+    remainingLeaseMs: number | undefined,
+    storeVersion: string
+  ): void {
+    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
+    });
+  }
+
+  private finishResolutionCore(key: string): void {
+    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);
+  }
+
+  private currentEpochCore(key: string): number {
+    return this.routeEpochs.get(key) ?? 0;
+  }
+}
+
+async function resolveEntrySpotPeerInMeshes(
+  rows: Pick<ZLinkStoreLocationResolvers, 'resolveEntrySpotNode'>,
+  spotId: SpotId,
+  meshNames: readonly string[],
+  signal?: AbortSignal
+): Promise<Awaited<ReturnType<ZLinkStoreLocationResolvers['resolveEntrySpotNode']>>> {
+  return await rows.resolveEntrySpotNode(spotId, meshNames, signal);
+}