@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/locations/relocation-blob.ts

@@ -1,3 +1,9 @@
+import {
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind
+} from '../../contracts/Errors/ZLinkFrameworkException';
+import { isIndeterminateLocationStoreFailure } from './location-store-failure';
+import type { ZLinkRuntimeMetrics } from '../diagnostics/runtime-metrics';
 import { randomUUID } from 'node:crypto';
 import { awaitWithAbort, macrotaskBoundary } from '../abort';
 import type {
@@ -19,6 +25,22 @@ export async function putNewRelocationBlob(
   readonly reference: ZLinkBlobReference;
   readonly expiresAt: Date;
   readonly storeNow: Date;
+}> {
+  if (store instanceof ZLinkProviderRelocationRepository) {
+    return store.putNew(payload, retentionMs, signal);
+  }
+  return putNewRelocationBlobCore(store, payload, retentionMs, signal);
+}
+
+async function putNewRelocationBlobCore(
+  store: ZLinkRelocationStore,
+  payload: Uint8Array,
+  retentionMs: number,
+  signal?: AbortSignal
+): Promise<{
+  readonly reference: ZLinkBlobReference;
+  readonly expiresAt: Date;
+  readonly storeNow: Date;
 }> {
   let reference = relocationBlobReference(randomUUID());
   for (; ; await macrotaskBoundary()) {
@@ -26,7 +48,8 @@ export async function putNewRelocationBlob(
     let result: ZLinkBlobPutResult;
     try {
       result = await awaitWithAbort(store.put(reference, payload, retentionMs, signal), signal);
-    } catch {
+    } catch (error) {
+      if (!isRelocationProviderFailure(error)) throw error;
       signal?.throwIfAborted();
       const read = await awaitWithAbort(store.read(reference, signal), signal);
       if (read.kind === 'found' && Buffer.compare(read.bytes, payload) === 0) {
@@ -45,3 +68,54 @@ export async function putNewRelocationBlob(
     reference = relocationBlobReference(randomUUID());
   }
 }
+
+/** Observes provider requests before callers interpret or decode blob contents. */
+export class ZLinkProviderRelocationRepository implements ZLinkRelocationStore {
+  constructor(
+    private readonly provider: ZLinkRelocationStore,
+    private readonly metrics: ZLinkRuntimeMetrics
+  ) {}
+
+  putNew(payload: Uint8Array, retentionMs: number, signal?: AbortSignal) {
+    return this.observe(
+      'relocation_put',
+      () => putNewRelocationBlobCore(this.provider, payload, retentionMs, signal),
+      signal
+    );
+  }
+  put(...args: Parameters<ZLinkRelocationStore['put']>) {
+    return this.observe('relocation_put', () => this.provider.put(...args), args[3]);
+  }
+  read(...args: Parameters<ZLinkRelocationStore['read']>) {
+    return this.observe('relocation_get', () => this.provider.read(...args), args[1]);
+  }
+  renew(...args: Parameters<ZLinkRelocationStore['renew']>) {
+    return this.observe('relocation_put', () => this.provider.renew(...args), args[2]);
+  }
+  delete(...args: Parameters<ZLinkRelocationStore['delete']>) {
+    return this.observe('relocation_delete', () => this.provider.delete(...args), args[1]);
+  }
+  private async observe<T>(
+    operation: 'relocation_put' | 'relocation_get' | 'relocation_delete',
+    request: () => Promise<T>,
+    signal?: AbortSignal
+  ): Promise<T> {
+    try {
+      return await request();
+    } catch (error) {
+      if (isRelocationProviderFailure(error, signal)) {
+        this.metrics.recordLocationStoreError(operation);
+      }
+      throw error;
+    }
+  }
+}
+
+function isRelocationProviderFailure(error: unknown, signal?: AbortSignal): boolean {
+  return (
+    isIndeterminateLocationStoreFailure(error, signal) &&
+    !(
+      error instanceof ZLinkFrameworkException && error.kind !== ZLinkFrameworkErrorKind.Unavailable
+    )
+  );
+}

package/src/runtime/locations/request-source-resolver.ts

@@ -0,0 +1,138 @@
+import type { RoutingId } from '../../contracts/Common';
+import type { ZLinkMeshNodeDescriptor } from '../../contracts/Locations/Rows';
+import type { ZLinkLocationOwnerToken } from './internal-location-contracts';
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
+import { awaitWithAbort, throwIfAborted } from '../abort';
+
+/** Source request owner values the first accepting owner records (Location runtime §9.3). */
+export interface ZLinkRequestSourceFence {
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+  readonly nodeRid: RoutingId;
+  readonly nodeGeneration: bigint;
+}
+
+export interface ZLinkRequestSourceResolverOptions {
+  readonly listLiveMeshNodes: (
+    meshName: string,
+    signal?: AbortSignal
+  ) => Promise<readonly ZLinkMeshNodeDescriptor[]>;
+  readonly remainingOwnerTokenLeaseMs: (
+    owner: ZLinkLocationOwnerToken,
+    signal?: AbortSignal
+  ) => Promise<number>;
+  readonly monotonicNowMs?: () => number;
+}
+
+interface PolledSource {
+  readonly fence: ZLinkRequestSourceFence;
+  readonly leaseDeadlineMs: number;
+}
+
+/**
+ * Chooses the descriptor that supplies the source request owner values (Session·Actor binding
+ * §4): the admitted sender's descriptor with the exact RID and node lifecycle generation whose
+ * owner lease passes the Location runtime §4.1 check. Auto-connect polling keeps the live
+ * descriptors here with the local lease deadline computed from the same lease read. A sender
+ * missing from them is read from the Store once and kept with them.
+ */
+export class ZLinkRequestSourceResolver {
+  private readonly polled = new Map<string, Map<string, PolledSource>>();
+  private readonly monotonicNowMs: () => number;
+
+  constructor(private readonly options: ZLinkRequestSourceResolverOptions) {
+    this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+  }
+
+  /** Replaces the polled descriptors of one mesh with a live descriptor listing. */
+  async observeLiveDescriptors(
+    meshName: string,
+    descriptors: readonly ZLinkMeshNodeDescriptor[],
+    signal?: AbortSignal
+  ): Promise<void> {
+    const sources = new Map<string, PolledSource>();
+    for (const descriptor of descriptors) {
+      const source = await this.polledSource(descriptor, signal);
+      if (source !== undefined) sources.set(encodeRoutingIdStorageHex(descriptor.rid), source);
+    }
+    this.polled.set(meshName, sources);
+  }
+
+  /**
+   * Returns the recorded values, undefined when the sender has no live descriptor, or a promise
+   * while the Store is read once for a sender the polled descriptors do not contain.
+   */
+  accept(
+    meshName: string,
+    nodeRid: RoutingId,
+    nodeGeneration: bigint,
+    nodeRidStorageHex: string,
+    signal?: AbortSignal
+  ): ZLinkRequestSourceFence | undefined | Promise<ZLinkRequestSourceFence | undefined> {
+    throwIfAborted(signal);
+    const known = this.polled.get(meshName)?.get(nodeRidStorageHex);
+    if (known !== undefined && known.fence.nodeGeneration === nodeGeneration) {
+      return this.monotonicNowMs() < known.leaseDeadlineMs ? known.fence : undefined;
+    }
+    return this.readOnce(meshName, nodeRid, nodeGeneration, nodeRidStorageHex, signal);
+  }
+
+  private async readOnce(
+    meshName: string,
+    nodeRid: RoutingId,
+    nodeGeneration: bigint,
+    nodeRidStorageHex: string,
+    signal?: AbortSignal
+  ): Promise<ZLinkRequestSourceFence | undefined> {
+    // The Store boundary already classifies provider failures as Unavailable. Preserve their
+    // cause for the ingress error reporter, and let programming errors propagate unchanged.
+    const descriptors = await awaitWithAbort(
+      this.options.listLiveMeshNodes(meshName, signal),
+      signal
+    );
+    const descriptor = descriptors.find(
+      (value) => routingIdsEqual(value.rid, nodeRid) && value.lifecycleGeneration === nodeGeneration
+    );
+    const source =
+      descriptor === undefined ? undefined : await this.polledSource(descriptor, signal);
+    throwIfAborted(signal);
+    if (source === undefined) return undefined;
+    let sources = this.polled.get(meshName);
+    if (sources === undefined) {
+      sources = new Map();
+      this.polled.set(meshName, sources);
+    }
+    sources.set(nodeRidStorageHex, source);
+    return source.fence;
+  }
+
+  private async polledSource(
+    descriptor: ZLinkMeshNodeDescriptor,
+    signal?: AbortSignal
+  ): Promise<PolledSource | undefined> {
+    if (
+      descriptor.ownerId.length === 0 ||
+      descriptor.leaseGeneration <= 0n ||
+      descriptor.lifecycleGeneration <= 0n
+    ) {
+      return undefined;
+    }
+    const remainingMs = await awaitWithAbort(
+      this.options.remainingOwnerTokenLeaseMs(
+        { ownerId: descriptor.ownerId, leaseGeneration: descriptor.leaseGeneration },
+        signal
+      ),
+      signal
+    );
+    if (remainingMs <= 0) return undefined;
+    return {
+      fence: {
+        ownerId: descriptor.ownerId,
+        leaseGeneration: descriptor.leaseGeneration,
+        nodeRid: descriptor.rid,
+        nodeGeneration: descriptor.lifecycleGeneration
+      },
+      leaseDeadlineMs: this.monotonicNowMs() + remainingMs
+    };
+  }
+}

package/src/runtime/locations/resolvers.ts

@@ -17,7 +17,7 @@ import {
   createInternalFrameworkException,
   internalFrameworkErrorKind
 } from '../framework-errors-internal';
-import { routingIdsEqual } from '../routing-id';
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
 import {
   type SpotHandle,
   type ZLinkActorSpotHandleResolver,
@@ -282,7 +282,7 @@ export class ZLinkStoreLocationResolvers
         descriptor.objectRole === ZLinkObjectRole.Server &&
         descriptor.placementWeight > 0 &&
         !routingIdsEqual(descriptor.rid, excludedNodeRid) &&
-        !excludedCandidateRids.has(String(descriptor.rid)) &&
+        !excludedCandidateRids.has(encodeRoutingIdStorageHex(descriptor.rid)) &&
         capacity.active + capacity.reserved < capacity.limit &&
         descriptor.objectCapabilities.some(
           (candidate) => candidate.objectKind === 'actor' && candidate.stableType === actorType

package/src/runtime/locations/runtime.ts

@@ -1,3 +1,5 @@
+import { ZLinkDescriptorPublicationUnconfirmedError } from './descriptor-publication';
+import { isIndeterminateLocationStoreFailure } from './location-store-failure';
 import { listAllMeshNodeDescriptors } from './location-store-pages';
 import { MILLISECONDS_PER_SECOND } from '../diagnostics/runtime-metrics';
 import { ZLINK_PROVIDER_MAX_PAGE_SIZE } from '../../contracts/Locations/Stores';
@@ -148,7 +150,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   private readonly liveRows: ZLinkLiveRowFilter;
   private readonly leaseTracker: ZLinkOwnerLeaseTracker;
   private readonly ownershipLostHandlers = new Set<(event: ZLinkOwnershipLostEvent) => void>();
-  private readonly ownerLeaseRenewedHandlers = new Set<(renewal: ZLinkOwnerLeaseRenewed) => void>();
+  private readonly ownerLeaseRenewedHandlers = new Set<
+    (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  >();
   private readonly ownerLeaseRenewalFailedHandlers = new Set<() => void>();
   private heartbeatTimer: unknown;
   private heartbeatRenewal?: Promise<unknown>;
@@ -162,7 +166,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     readonly name: string;
   }[];
   private readonly rewriteAuthorityPayloadForOwner?: ZLinkLocationRuntimeOptions['rewriteAuthorityPayloadForOwner'];
-  private nextLeaseRenewAtMs?: number;
+  private leaseOperationStartedAtMs = 0;
   private ownerToken?: ZLinkLocationOwnerToken;
   private lastOwnerToken?: ZLinkLocationOwnerToken;
   private ownerLeaseDeadlineMs?: number;
@@ -216,9 +220,22 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     return this.ownerToken;
   }
 
+  /** Location runtime §5: a startup Store request ends within the renew timeout. */
+  async writeDescriptor<T>(
+    action: (signal?: AbortSignal) => Promise<T>,
+    signal?: AbortSignal
+  ): Promise<T> {
+    try {
+      return await withTimeout(action, this.options.ownerLeaseRenewTimeoutMs, signal);
+    } catch (error) {
+      if (!isIndeterminateLocationStoreFailure(error, signal)) throw error;
+      throw new ZLinkDescriptorPublicationUnconfirmedError(error);
+    }
+  }
+
   closeOwnerLeaseAdmission(error: unknown): void {
     this.ownerLeaseDeadlineMs = undefined;
-    this.recordFailure(errorMessage(error), 'owner_lease_recovery');
+    this.recordFailure(errorMessage(error));
   }
 
   async reclaimOwnerAuthorities(signal?: AbortSignal): Promise<void> {
@@ -308,11 +325,15 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     this.ownershipLostHandlers.delete(handler);
   }
 
-  addOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void {
+  addOwnerLeaseRenewedHandler(
+    handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  ): void {
     this.ownerLeaseRenewedHandlers.add(handler);
   }
 
-  removeOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void {
+  removeOwnerLeaseRenewedHandler(
+    handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void
+  ): void {
     this.ownerLeaseRenewedHandlers.delete(handler);
   }
 
@@ -342,12 +363,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     const claim = this.renewOwnerLeaseOnce(signal, shutdownSignal);
     this.heartbeatRenewal = claim;
     try {
-      const claimed = await claim;
-      if (claimed) {
-        this.scheduleHeartbeat();
-        return;
-      }
-      this.nextLeaseRenewAtMs = this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
+      await claim;
       this.scheduleHeartbeat();
     } catch (error) {
       this.started = false;
@@ -362,7 +378,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       this.clearTimer(this.heartbeatTimer);
       this.heartbeatTimer = undefined;
     }
-    this.nextLeaseRenewAtMs = undefined;
+    this.leaseOperationStartedAtMs = 0;
     this.ownerLeaseDeadlineMs = undefined;
     await this.cleanupOwner(signal);
   }
@@ -419,9 +435,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       return await this.claimFreshOwnerLease(signal, shutdownSignal);
     }
 
-    const wasOwnerLeaseUsable = this.ownerLeaseUsable;
     try {
       const renewStartedAtMs = this.monotonicNowMs();
+      this.leaseOperationStartedAtMs = renewStartedAtMs;
       const result = await withTimeout(
         (renewSignal) =>
           this.stores.ownerLeaseStore.renewOwnerLease(
@@ -448,6 +464,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         // another heartbeat interval.
         return await this.claimFreshOwnerLease(signal, shutdownSignal);
       }
+      const wasOwnerLeaseUsable = this.ownerLeaseUsable;
       this.ownerLeaseHealthy = true;
       this.ownerLeaseRenewedAt = result.storeNow;
       this.setOwnerLeaseDeadline(
@@ -457,14 +474,14 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         result.storeNow
       );
       this.lastError = undefined;
-      if (!wasOwnerLeaseUsable) {
-        for (const handler of this.ownerLeaseRenewedHandlers) handler(result);
+      for (const handler of this.ownerLeaseRenewedHandlers) {
+        handler(result, wasOwnerLeaseUsable);
       }
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
       this.recordOwnerLeaseRenewFailure();
-      this.recordFailure(errorMessage(error), 'lease_renew');
+      this.recordFailure(errorMessage(error));
       for (const handler of this.ownerLeaseRenewalFailedHandlers) handler();
       return false;
     }
@@ -475,21 +492,26 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     shutdownSignal?: () => AbortSignal
   ): Promise<boolean> {
     const claimStartedAtMs = this.monotonicNowMs();
-    const timeoutDeadline = performance.now() + this.options.ownerLeaseRenewTimeoutMs;
+    this.leaseOperationStartedAtMs = claimStartedAtMs;
+    const timeoutStartedAtMs = performance.now();
     let claim: Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>;
     try {
-      claim = await this.claimOwnerLeaseWithConfirmation(timeoutDeadline, signal, shutdownSignal);
+      claim = await this.claimOwnerLeaseWithConfirmation(
+        timeoutStartedAtMs,
+        signal,
+        shutdownSignal
+      );
     } catch (error) {
       if (signal?.aborted === true) throw error;
       if (error instanceof ZLinkOwnerLeaseClaimError) throw error;
       this.recordOwnerLeaseRenewFailure();
-      this.recordFailure(errorMessage(error), 'owner_lease_claim');
+      this.recordFailure(errorMessage(error));
       return false;
     }
     const claimCompletedAtMs = this.monotonicNowMs();
     if (claim.kind !== 'claimed') {
       const error = new ZLinkOwnerLeaseClaimError(claim.kind);
-      this.recordFailure(error.message, 'owner_lease_claim');
+      this.recordFailure(error.message);
       throw error;
     }
     try {
@@ -508,24 +530,26 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         claim.storeNow
       );
       this.lastError = undefined;
-      this.nextLeaseRenewAtMs = this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
       for (const handler of this.ownerLeaseRenewedHandlers) {
-        handler({
-          kind: 'renewed',
-          leaseExpiresAt: claim.leaseExpiresAt,
-          storeNow: claim.storeNow
-        });
+        handler(
+          {
+            kind: 'renewed',
+            leaseExpiresAt: claim.leaseExpiresAt,
+            storeNow: claim.storeNow
+          },
+          false
+        );
       }
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
-      this.recordFailure(errorMessage(error), 'owner_lease_claim');
+      this.recordFailure(errorMessage(error));
       return false;
     }
   }
 
   private async claimOwnerLeaseWithConfirmation(
-    timeoutDeadline: number,
+    timeoutStartedAtMs: number,
     signal?: AbortSignal,
     shutdownSignal?: () => AbortSignal
   ): Promise<Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>> {
@@ -540,7 +564,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
             this.options.ownerLeaseTtlMs,
             claimSignal
           )),
-        remainingTimeoutMs(timeoutDeadline),
+        remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs),
         signal
       );
     } catch (error) {
@@ -550,7 +574,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         try {
           await withTimeout(
             () => request!,
-            cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined,
+            cleanupSignal === undefined
+              ? remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs)
+              : undefined,
             cleanupSignal
           );
         } catch (completionError) {
@@ -561,13 +587,13 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
             throw new ZLinkOwnerCleanupError(completionError);
           }
           if (!isAbortError(completionError)) {
-            this.recordFailure(errorMessage(completionError), 'owner_lease_claim');
+            this.recordFailure(errorMessage(completionError));
           }
         }
       }
       const confirmed = await this.confirmOwnerLease(
         error,
-        timeoutDeadline,
+        timeoutStartedAtMs,
         signal,
         shutdownSignal
       );
@@ -577,13 +603,13 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     if (claim.kind !== 'conflict') return claim;
     const conflict = new ZLinkOwnerLeaseClaimError(claim.kind);
     return (
-      (await this.confirmOwnerLease(conflict, timeoutDeadline, signal, shutdownSignal)) ?? claim
+      (await this.confirmOwnerLease(conflict, timeoutStartedAtMs, signal, shutdownSignal)) ?? claim
     );
   }
 
   private async confirmOwnerLease(
     originalError: unknown,
-    timeoutDeadline: number,
+    timeoutStartedAtMs: number,
     signal?: AbortSignal,
     shutdownSignal?: () => AbortSignal
   ): Promise<
@@ -593,7 +619,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     const cancelled = signal?.aborted === true;
     const cleanupSignal = cancelled ? shutdownSignal?.() : undefined;
     const confirmationTimeoutMs =
-      cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined;
+      cleanupSignal === undefined
+        ? remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs)
+        : undefined;
     if (confirmationTimeoutMs !== undefined && confirmationTimeoutMs <= 0) throw originalError;
     let confirmed: Awaited<ReturnType<ZLinkOwnerLeaseStore['readOwnerLease']>>;
     try {
@@ -603,9 +631,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         cleanupSignal
       );
     } catch (confirmationError) {
-      this.recordFailure(errorMessage(confirmationError), 'owner_lease_claim_confirmation');
+      this.recordFailure(errorMessage(confirmationError));
       if (cancelled) throw new ZLinkOwnerCleanupError(confirmationError);
-      throw confirmationError;
+      throw originalError instanceof ZLinkOwnerLeaseClaimError ? originalError : confirmationError;
     }
     if (confirmed.kind !== 'found' || confirmed.token.ownerId !== this.ownerId) {
       throw originalError;
@@ -615,11 +643,13 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         await withTimeout(
           (releaseSignal) =>
             this.stores.ownerLeaseStore.releaseOwnerLease(confirmed.token, releaseSignal),
-          cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined,
+          cleanupSignal === undefined
+            ? remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs)
+            : undefined,
           cleanupSignal
         );
       } catch (releaseError) {
-        this.recordFailure(errorMessage(releaseError), 'owner_lease_release');
+        this.recordFailure(errorMessage(releaseError));
         throw new ZLinkOwnerCleanupError(releaseError);
       }
       throw originalError;
@@ -687,7 +717,10 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       updatedAt: new Date()
     };
     let result = await this.guardWrite(() =>
-      this.stores.locationStore.updateMeshNode(stamped, intent, signal)
+      this.writeDescriptor(
+        (writeSignal) => this.stores.locationStore.updateMeshNode(stamped, intent, writeSignal),
+        signal
+      )
     );
     if (
       intent === ZLinkLocationWriteIntent.Renew &&
@@ -699,7 +732,15 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       // NewClaim as a bounded fallback. If another owner has recreated the
       // row, NewClaim remains rejected and the caller keeps the conflict.
       result = await this.guardWrite(() =>
-        this.stores.locationStore.updateMeshNode(stamped, ZLinkLocationWriteIntent.NewClaim, signal)
+        this.writeDescriptor(
+          (writeSignal) =>
+            this.stores.locationStore.updateMeshNode(
+              stamped,
+              ZLinkLocationWriteIntent.NewClaim,
+              writeSignal
+            ),
+          signal
+        )
       );
     }
     this.notifyIfStale(
@@ -906,7 +947,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   }
 
   reportDiscoveryFailure(error: unknown): void {
-    this.recordFailure(errorMessage(error), 'read');
+    this.recordFailure(errorMessage(error));
   }
 
   async listPeerLocations(
@@ -939,6 +980,14 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     return live.map((row) => ({ ...row, endpoint: normalizeEndpoint(row.endpoint) }));
   }
 
+  /** Remaining exact owner lease from the same tracker that filters live descriptors. */
+  remainingOwnerTokenLeaseMs(
+    owner: ZLinkLocationOwnerToken,
+    signal?: AbortSignal
+  ): Promise<number> {
+    return this.leaseTracker.remainingOwnerTokenLeaseMs(owner, signal);
+  }
+
   async listMeshNodeDescriptors(
     meshName: string,
     page?: ZLinkPageRequest,
@@ -1250,8 +1299,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     if (!this.started) {
       return;
     }
-    const scheduledAt =
-      this.nextLeaseRenewAtMs ?? this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
+    const scheduledAt = this.leaseOperationStartedAtMs + this.options.ownerLeaseRenewIntervalMs;
     const delayMs = Math.max(0, scheduledAt - this.monotonicNowMs());
     this.heartbeatTimer = this.setTimer(() => {
       this.heartbeatTimer = undefined;
@@ -1259,13 +1307,12 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       for (const scope of this.leaseScopes) {
         this.metrics?.recordOwnerLeaseRenewLateness(lateness, scope.kind, scope.name);
       }
-      this.nextLeaseRenewAtMs = this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
       if (
         this.ownerLeaseDeadlineMs !== undefined &&
         this.monotonicNowMs() >= this.ownerLeaseDeadlineMs
       ) {
         this.ownerLeaseHealthy = false;
-        this.recordFailure('Owner lease expired before renewal completed.', 'lease_expired');
+        this.recordFailure('Owner lease expired before renewal completed.');
         for (const handler of this.ownerLeaseRenewalFailedHandlers) handler();
       }
       const renewal = this.renewOwnerLeaseOnce()
@@ -1290,7 +1337,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     try {
       return await write();
     } catch (error) {
-      this.recordFailure(errorMessage(error), 'compare_exchange');
+      this.recordFailure(errorMessage(error));
       throw error;
     }
   }
@@ -1301,7 +1348,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     try {
       return await write();
     } catch (error) {
-      this.recordFailure(errorMessage(error), 'compare_exchange');
+      this.recordFailure(errorMessage(error));
       throw error;
     }
   }
@@ -1311,12 +1358,6 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     kind: ZLinkLocationKind,
     key: string
   ): void {
-    if (
-      result.status === ZLinkLocationWriteStatus.IgnoredStale ||
-      result.status === ZLinkLocationWriteStatus.RejectedConflict
-    ) {
-      this.metrics?.recordLocationStoreError('compare_exchange');
-    }
     if (result.status !== ZLinkLocationWriteStatus.IgnoredStale) {
       return;
     }
@@ -1330,12 +1371,6 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     kind: ZLinkLocationKind,
     key: string
   ): void {
-    if (
-      status === ZLinkLocationWriteStatus.IgnoredStale ||
-      status === ZLinkLocationWriteStatus.RejectedConflict
-    ) {
-      this.metrics?.recordLocationStoreError('compare_exchange');
-    }
     if (status !== ZLinkLocationWriteStatus.IgnoredStale) {
       return;
     }
@@ -1344,8 +1379,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     }
   }
 
-  private recordFailure(message: string, operation = 'read'): void {
-    this.metrics?.recordLocationStoreError(operation);
+  private recordFailure(message: string): void {
     this.ownerLeaseHealthy = false;
     this.lastError = message;
   }
@@ -1413,8 +1447,8 @@ class OwnerLeaseRenewTimeoutError extends Error {
   }
 }
 
-function remainingTimeoutMs(timeoutDeadline: number): number {
-  return Math.max(0, timeoutDeadline - performance.now());
+function remainingTimeoutMs(timeoutStartedAtMs: number, timeoutMs: number): number {
+  return Math.max(0, timeoutMs - (performance.now() - timeoutStartedAtMs));
 }
 
 function errorMessage(error: unknown): string {