@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/locations/relocation-blob.d.ts

@@ -1,7 +1,24 @@
-import type { ZLinkBlobReference, ZLinkRelocationStore } from '../../contracts/Locations/RelocationStore';
+import type { ZLinkRuntimeMetrics } from '../diagnostics/runtime-metrics';
+import type { ZLinkBlobReference, ZLinkBlobPutResult, ZLinkRelocationStore } from '../../contracts/Locations/RelocationStore';
 export declare function relocationBlobReference(value: string): ZLinkBlobReference;
 export declare function putNewRelocationBlob(store: ZLinkRelocationStore, payload: Uint8Array, retentionMs: number, signal?: AbortSignal): Promise<{
     readonly reference: ZLinkBlobReference;
     readonly expiresAt: Date;
     readonly storeNow: Date;
 }>;
+/** Observes provider requests before callers interpret or decode blob contents. */
+export declare class ZLinkProviderRelocationRepository implements ZLinkRelocationStore {
+    private readonly provider;
+    private readonly metrics;
+    constructor(provider: ZLinkRelocationStore, metrics: ZLinkRuntimeMetrics);
+    putNew(payload: Uint8Array, retentionMs: number, signal?: AbortSignal): Promise<{
+        readonly reference: ZLinkBlobReference;
+        readonly expiresAt: Date;
+        readonly storeNow: Date;
+    }>;
+    put(...args: Parameters<ZLinkRelocationStore['put']>): Promise<ZLinkBlobPutResult>;
+    read(...args: Parameters<ZLinkRelocationStore['read']>): Promise<import("../../contracts/Locations/RelocationStore").ZLinkBlobReadResult>;
+    renew(...args: Parameters<ZLinkRelocationStore['renew']>): Promise<import("../../contracts/Locations/RelocationStore").ZLinkBlobRenewResult>;
+    delete(...args: Parameters<ZLinkRelocationStore['delete']>): Promise<void>;
+    private observe;
+}

package/dist/runtime/locations/relocation-blob.js

@@ -1,13 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkProviderRelocationRepository = void 0;
 exports.relocationBlobReference = relocationBlobReference;
 exports.putNewRelocationBlob = putNewRelocationBlob;
+const ZLinkFrameworkException_1 = require("../../contracts/Errors/ZLinkFrameworkException");
+const location_store_failure_1 = require("./location-store-failure");
 const node_crypto_1 = require("node:crypto");
 const abort_1 = require("../abort");
 function relocationBlobReference(value) {
     return { value };
 }
 async function putNewRelocationBlob(store, payload, retentionMs, signal) {
+    if (store instanceof ZLinkProviderRelocationRepository) {
+        return store.putNew(payload, retentionMs, signal);
+    }
+    return putNewRelocationBlobCore(store, payload, retentionMs, signal);
+}
+async function putNewRelocationBlobCore(store, payload, retentionMs, signal) {
     let reference = relocationBlobReference((0, node_crypto_1.randomUUID)());
     for (;; await (0, abort_1.macrotaskBoundary)()) {
         signal?.throwIfAborted();
@@ -15,7 +24,9 @@ async function putNewRelocationBlob(store, payload, retentionMs, signal) {
         try {
             result = await (0, abort_1.awaitWithAbort)(store.put(reference, payload, retentionMs, signal), signal);
         }
-        catch {
+        catch (error) {
+            if (!isRelocationProviderFailure(error))
+                throw error;
             signal?.throwIfAborted();
             const read = await (0, abort_1.awaitWithAbort)(store.read(reference, signal), signal);
             if (read.kind === 'found' && Buffer.compare(read.bytes, payload) === 0) {
@@ -35,3 +46,43 @@ async function putNewRelocationBlob(store, payload, retentionMs, signal) {
         reference = relocationBlobReference((0, node_crypto_1.randomUUID)());
     }
 }
+/** Observes provider requests before callers interpret or decode blob contents. */
+class ZLinkProviderRelocationRepository {
+    provider;
+    metrics;
+    constructor(provider, metrics) {
+        this.provider = provider;
+        this.metrics = metrics;
+    }
+    putNew(payload, retentionMs, signal) {
+        return this.observe('relocation_put', () => putNewRelocationBlobCore(this.provider, payload, retentionMs, signal), signal);
+    }
+    put(...args) {
+        return this.observe('relocation_put', () => this.provider.put(...args), args[3]);
+    }
+    read(...args) {
+        return this.observe('relocation_get', () => this.provider.read(...args), args[1]);
+    }
+    renew(...args) {
+        return this.observe('relocation_put', () => this.provider.renew(...args), args[2]);
+    }
+    delete(...args) {
+        return this.observe('relocation_delete', () => this.provider.delete(...args), args[1]);
+    }
+    async observe(operation, request, signal) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (isRelocationProviderFailure(error, signal)) {
+                this.metrics.recordLocationStoreError(operation);
+            }
+            throw error;
+        }
+    }
+}
+exports.ZLinkProviderRelocationRepository = ZLinkProviderRelocationRepository;
+function isRelocationProviderFailure(error, signal) {
+    return ((0, location_store_failure_1.isIndeterminateLocationStoreFailure)(error, signal) &&
+        !(error instanceof ZLinkFrameworkException_1.ZLinkFrameworkException && error.kind !== ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.Unavailable));
+}

package/dist/runtime/locations/request-source-resolver.d.ts

@@ -0,0 +1,37 @@
+import type { RoutingId } from '../../contracts/Common';
+import type { ZLinkMeshNodeDescriptor } from '../../contracts/Locations/Rows';
+import type { ZLinkLocationOwnerToken } from './internal-location-contracts';
+/** 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;
+}
+/**
+ * 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 declare class ZLinkRequestSourceResolver {
+    private readonly options;
+    private readonly polled;
+    private readonly monotonicNowMs;
+    constructor(options: ZLinkRequestSourceResolverOptions);
+    /** Replaces the polled descriptors of one mesh with a live descriptor listing. */
+    observeLiveDescriptors(meshName: string, descriptors: readonly ZLinkMeshNodeDescriptor[], signal?: AbortSignal): Promise<void>;
+    /**
+     * 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>;
+    private readOnce;
+    private polledSource;
+}

package/dist/runtime/locations/request-source-resolver.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRequestSourceResolver = void 0;
+const routing_id_1 = require("../routing-id");
+const abort_1 = require("../abort");
+/**
+ * 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.
+ */
+class ZLinkRequestSourceResolver {
+    options;
+    polled = new Map();
+    monotonicNowMs;
+    constructor(options) {
+        this.options = options;
+        this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+    }
+    /** Replaces the polled descriptors of one mesh with a live descriptor listing. */
+    async observeLiveDescriptors(meshName, descriptors, signal) {
+        const sources = new Map();
+        for (const descriptor of descriptors) {
+            const source = await this.polledSource(descriptor, signal);
+            if (source !== undefined)
+                sources.set((0, routing_id_1.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, nodeRid, nodeGeneration, nodeRidStorageHex, signal) {
+        (0, abort_1.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);
+    }
+    async readOnce(meshName, nodeRid, nodeGeneration, nodeRidStorageHex, signal) {
+        // 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 (0, abort_1.awaitWithAbort)(this.options.listLiveMeshNodes(meshName, signal), signal);
+        const descriptor = descriptors.find((value) => (0, routing_id_1.routingIdsEqual)(value.rid, nodeRid) && value.lifecycleGeneration === nodeGeneration);
+        const source = descriptor === undefined ? undefined : await this.polledSource(descriptor, signal);
+        (0, abort_1.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;
+    }
+    async polledSource(descriptor, signal) {
+        if (descriptor.ownerId.length === 0 ||
+            descriptor.leaseGeneration <= 0n ||
+            descriptor.lifecycleGeneration <= 0n) {
+            return undefined;
+        }
+        const remainingMs = await (0, abort_1.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
+        };
+    }
+}
+exports.ZLinkRequestSourceResolver = ZLinkRequestSourceResolver;

package/dist/runtime/locations/resolvers.js

@@ -104,7 +104,7 @@ class ZLinkStoreLocationResolvers {
                 descriptor.objectRole === internal_location_contracts_1.ZLinkObjectRole.Server &&
                 descriptor.placementWeight > 0 &&
                 !(0, routing_id_1.routingIdsEqual)(descriptor.rid, excludedNodeRid) &&
-                !excludedCandidateRids.has(String(descriptor.rid)) &&
+                !excludedCandidateRids.has((0, routing_id_1.encodeRoutingIdStorageHex)(descriptor.rid)) &&
                 capacity.active + capacity.reserved < capacity.limit &&
                 descriptor.objectCapabilities.some((candidate) => candidate.objectKind === 'actor' && candidate.stableType === actorType));
         });

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

@@ -83,7 +83,7 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     private readonly meshNames;
     private readonly leaseScopes;
     private readonly rewriteAuthorityPayloadForOwner?;
-    private nextLeaseRenewAtMs?;
+    private leaseOperationStartedAtMs;
     private ownerToken?;
     private lastOwnerToken?;
     private ownerLeaseDeadlineMs?;
@@ -95,13 +95,15 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     get isStarted(): boolean;
     get nodeRid(): RoutingId | undefined;
     get currentOwnerToken(): ZLinkLocationOwnerToken | undefined;
+    /** Location runtime §5: a startup Store request ends within the renew timeout. */
+    writeDescriptor<T>(action: (signal?: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
     closeOwnerLeaseAdmission(error: unknown): void;
     reclaimOwnerAuthorities(signal?: AbortSignal): Promise<void>;
     private readAllAuthorityEntries;
     addOwnershipLostHandler(handler: (event: ZLinkOwnershipLostEvent) => void): void;
     removeOwnershipLostHandler(handler: (event: ZLinkOwnershipLostEvent) => void): void;
-    addOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void;
-    removeOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void;
+    addOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void): void;
+    removeOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed, wasOwnerLeaseUsable: boolean) => void): void;
     addOwnerLeaseRenewalFailedHandler(handler: () => void): void;
     removeOwnerLeaseRenewalFailedHandler(handler: () => void): void;
     start(nodeRid: RoutingId): Promise<void>;
@@ -128,6 +130,8 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     reportDiscoveryFailure(error: unknown): void;
     listPeerLocations(filter: ZLinkPeerLocationFilter, signal?: AbortSignal): Promise<readonly ZLinkPeerLocation[]>;
     listLiveMeshNodes(meshName: string, signal?: AbortSignal): Promise<readonly ZLinkMeshNodeDescriptor[]>;
+    /** Remaining exact owner lease from the same tracker that filters live descriptors. */
+    remainingOwnerTokenLeaseMs(owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<number>;
     listMeshNodeDescriptors(meshName: string, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkMeshNodeDescriptor>>;
     listSpotLocations(filter: ZLinkSpotLocationFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkSpotLocation>>;
     listActorLocations(filter: ZLinkActorLocationFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkActorLocation>>;

package/dist/runtime/locations/runtime.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocationRuntime = exports.ZLinkOwnerLeaseClaimError = exports.ZLinkOwnerCleanupError = void 0;
+const descriptor_publication_1 = require("./descriptor-publication");
+const location_store_failure_1 = require("./location-store-failure");
 const location_store_pages_1 = require("./location-store-pages");
 const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 const Stores_1 = require("../../contracts/Locations/Stores");
@@ -52,7 +54,7 @@ class ZLinkLocationRuntime {
     meshNames;
     leaseScopes;
     rewriteAuthorityPayloadForOwner;
-    nextLeaseRenewAtMs;
+    leaseOperationStartedAtMs = 0;
     ownerToken;
     lastOwnerToken;
     ownerLeaseDeadlineMs;
@@ -97,9 +99,20 @@ class ZLinkLocationRuntime {
     get currentOwnerToken() {
         return this.ownerToken;
     }
+    /** Location runtime §5: a startup Store request ends within the renew timeout. */
+    async writeDescriptor(action, signal) {
+        try {
+            return await withTimeout(action, this.options.ownerLeaseRenewTimeoutMs, signal);
+        }
+        catch (error) {
+            if (!(0, location_store_failure_1.isIndeterminateLocationStoreFailure)(error, signal))
+                throw error;
+            throw new descriptor_publication_1.ZLinkDescriptorPublicationUnconfirmedError(error);
+        }
+    }
     closeOwnerLeaseAdmission(error) {
         this.ownerLeaseDeadlineMs = undefined;
-        this.recordFailure(errorMessage(error), 'owner_lease_recovery');
+        this.recordFailure(errorMessage(error));
     }
     async reclaimOwnerAuthorities(signal) {
         const owner = this.ownerToken;
@@ -191,12 +204,7 @@ class ZLinkLocationRuntime {
         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) {
@@ -211,7 +219,7 @@ class ZLinkLocationRuntime {
             this.clearTimer(this.heartbeatTimer);
             this.heartbeatTimer = undefined;
         }
-        this.nextLeaseRenewAtMs = undefined;
+        this.leaseOperationStartedAtMs = 0;
         this.ownerLeaseDeadlineMs = undefined;
         await this.cleanupOwner(signal);
     }
@@ -260,9 +268,9 @@ class ZLinkLocationRuntime {
         if (this.ownerToken === undefined) {
             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(this.ownerToken, this.options.ownerLeaseTtlMs, renewSignal), this.options.ownerLeaseRenewTimeoutMs, signal);
             const renewCompletedAtMs = this.monotonicNowMs();
             if (result.kind !== 'renewed') {
@@ -281,13 +289,13 @@ class ZLinkLocationRuntime {
                 // another heartbeat interval.
                 return await this.claimFreshOwnerLease(signal, shutdownSignal);
             }
+            const wasOwnerLeaseUsable = this.ownerLeaseUsable;
             this.ownerLeaseHealthy = true;
             this.ownerLeaseRenewedAt = result.storeNow;
             this.setOwnerLeaseDeadline(renewStartedAtMs, renewCompletedAtMs, result.leaseExpiresAt, 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;
         }
@@ -295,7 +303,7 @@ class ZLinkLocationRuntime {
             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;
@@ -303,10 +311,11 @@ class ZLinkLocationRuntime {
     }
     async claimFreshOwnerLease(signal, shutdownSignal) {
         const claimStartedAtMs = this.monotonicNowMs();
-        const timeoutDeadline = performance.now() + this.options.ownerLeaseRenewTimeoutMs;
+        this.leaseOperationStartedAtMs = claimStartedAtMs;
+        const timeoutStartedAtMs = performance.now();
         let claim;
         try {
-            claim = await this.claimOwnerLeaseWithConfirmation(timeoutDeadline, signal, shutdownSignal);
+            claim = await this.claimOwnerLeaseWithConfirmation(timeoutStartedAtMs, signal, shutdownSignal);
         }
         catch (error) {
             if (signal?.aborted === true)
@@ -314,13 +323,13 @@ class ZLinkLocationRuntime {
             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 {
@@ -334,29 +343,28 @@ class ZLinkLocationRuntime {
             this.ownerLeaseRenewedAt = claim.storeNow;
             this.setOwnerLeaseDeadline(claimStartedAtMs, claimCompletedAtMs, claim.leaseExpiresAt, 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
-                });
+                }, false);
             }
             return true;
         }
         catch (error) {
             if (signal?.aborted === true)
                 throw error;
-            this.recordFailure(errorMessage(error), 'owner_lease_claim');
+            this.recordFailure(errorMessage(error));
             return false;
         }
     }
-    async claimOwnerLeaseWithConfirmation(timeoutDeadline, signal, shutdownSignal) {
+    async claimOwnerLeaseWithConfirmation(timeoutStartedAtMs, signal, shutdownSignal) {
         signal?.throwIfAborted();
         let claim;
         let request;
         try {
-            claim = await withTimeout((claimSignal) => (request = this.stores.ownerLeaseStore.claimOwnerLease(this.ownerId, this.options.ownerLeaseTtlMs, claimSignal)), remainingTimeoutMs(timeoutDeadline), signal);
+            claim = await withTimeout((claimSignal) => (request = this.stores.ownerLeaseStore.claimOwnerLease(this.ownerId, this.options.ownerLeaseTtlMs, claimSignal)), remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs), signal);
         }
         catch (error) {
             if (error instanceof OwnerLeaseRenewTimeoutError)
@@ -364,7 +372,9 @@ class ZLinkLocationRuntime {
             if (signal?.aborted === true && request !== undefined) {
                 const cleanupSignal = shutdownSignal?.();
                 try {
-                    await withTimeout(() => request, cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined, cleanupSignal);
+                    await withTimeout(() => request, cleanupSignal === undefined
+                        ? remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs)
+                        : undefined, cleanupSignal);
                 }
                 catch (completionError) {
                     if (cleanupSignal?.aborted === true ||
@@ -372,11 +382,11 @@ class ZLinkLocationRuntime {
                         throw new ZLinkOwnerCleanupError(completionError);
                     }
                     if (!(0, abort_1.isAbortError)(completionError)) {
-                        this.recordFailure(errorMessage(completionError), 'owner_lease_claim');
+                        this.recordFailure(errorMessage(completionError));
                     }
                 }
             }
-            const confirmed = await this.confirmOwnerLease(error, timeoutDeadline, signal, shutdownSignal);
+            const confirmed = await this.confirmOwnerLease(error, timeoutStartedAtMs, signal, shutdownSignal);
             if (confirmed !== undefined)
                 return confirmed;
             throw error;
@@ -384,12 +394,14 @@ class ZLinkLocationRuntime {
         if (claim.kind !== 'conflict')
             return claim;
         const conflict = new ZLinkOwnerLeaseClaimError(claim.kind);
-        return ((await this.confirmOwnerLease(conflict, timeoutDeadline, signal, shutdownSignal)) ?? claim);
+        return ((await this.confirmOwnerLease(conflict, timeoutStartedAtMs, signal, shutdownSignal)) ?? claim);
     }
-    async confirmOwnerLease(originalError, timeoutDeadline, signal, shutdownSignal) {
+    async confirmOwnerLease(originalError, timeoutStartedAtMs, signal, shutdownSignal) {
         const cancelled = signal?.aborted === true;
         const cleanupSignal = cancelled ? shutdownSignal?.() : undefined;
-        const confirmationTimeoutMs = cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined;
+        const confirmationTimeoutMs = cleanupSignal === undefined
+            ? remainingTimeoutMs(timeoutStartedAtMs, this.options.ownerLeaseRenewTimeoutMs)
+            : undefined;
         if (confirmationTimeoutMs !== undefined && confirmationTimeoutMs <= 0)
             throw originalError;
         let confirmed;
@@ -397,20 +409,22 @@ class ZLinkLocationRuntime {
             confirmed = await withTimeout((readSignal) => this.stores.ownerLeaseStore.readOwnerLease(this.ownerId, readSignal), confirmationTimeoutMs, 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;
         }
         if (signal?.aborted === true) {
             try {
-                await withTimeout((releaseSignal) => this.stores.ownerLeaseStore.releaseOwnerLease(confirmed.token, releaseSignal), cleanupSignal === undefined ? remainingTimeoutMs(timeoutDeadline) : undefined, cleanupSignal);
+                await withTimeout((releaseSignal) => this.stores.ownerLeaseStore.releaseOwnerLease(confirmed.token, releaseSignal), 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;
@@ -464,7 +478,7 @@ class ZLinkLocationRuntime {
             // in-process result after the write completes.
             updatedAt: new Date()
         };
-        let result = await this.guardWrite(() => this.stores.locationStore.updateMeshNode(stamped, intent, signal));
+        let result = await this.guardWrite(() => this.writeDescriptor((writeSignal) => this.stores.locationStore.updateMeshNode(stamped, intent, writeSignal), signal));
         if (intent === internal_location_contracts_1.ZLinkLocationWriteIntent.Renew &&
             (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.RejectedConflict ||
                 result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.IgnoredStale)) {
@@ -472,7 +486,7 @@ class ZLinkLocationRuntime {
             // in-process owner token. Renew cannot recreate an absent row, so use
             // 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, internal_location_contracts_1.ZLinkLocationWriteIntent.NewClaim, signal));
+            result = await this.guardWrite(() => this.writeDescriptor((writeSignal) => this.stores.locationStore.updateMeshNode(stamped, internal_location_contracts_1.ZLinkLocationWriteIntent.NewClaim, writeSignal), signal));
         }
         this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Peer, `${descriptor.meshName}\0${String(descriptor.rid)}`);
         return result;
@@ -590,7 +604,7 @@ class ZLinkLocationRuntime {
         };
     }
     reportDiscoveryFailure(error) {
-        this.recordFailure(errorMessage(error), 'read');
+        this.recordFailure(errorMessage(error));
     }
     async listPeerLocations(filter, signal) {
         const rows = await this.stores.peerStore.listPeers(filter, signal);
@@ -606,6 +620,10 @@ class ZLinkLocationRuntime {
         const live = await this.liveRows.filter(rows, (row, signal) => this.leaseTracker.isOwnerTokenLive(row, signal), signal);
         return live.map((row) => ({ ...row, endpoint: (0, EndpointNotation_1.normalizeEndpoint)(row.endpoint) }));
     }
+    /** Remaining exact owner lease from the same tracker that filters live descriptors. */
+    remainingOwnerTokenLeaseMs(owner, signal) {
+        return this.leaseTracker.remainingOwnerTokenLeaseMs(owner, signal);
+    }
     async listMeshNodeDescriptors(meshName, page, signal) {
         const rows = await this.stores.locationStore.listMeshNodes(meshName, this.pageRequest(page), signal);
         const live = await this.liveRows.filter(rows.items, (row, signal) => this.leaseTracker.isOwnerTokenLive(row, signal), signal);
@@ -778,7 +796,7 @@ class ZLinkLocationRuntime {
         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;
@@ -786,11 +804,10 @@ class ZLinkLocationRuntime {
             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();
             }
@@ -811,7 +828,7 @@ class ZLinkLocationRuntime {
             return await write();
         }
         catch (error) {
-            this.recordFailure(errorMessage(error), 'compare_exchange');
+            this.recordFailure(errorMessage(error));
             throw error;
         }
     }
@@ -820,15 +837,11 @@ class ZLinkLocationRuntime {
             return await write();
         }
         catch (error) {
-            this.recordFailure(errorMessage(error), 'compare_exchange');
+            this.recordFailure(errorMessage(error));
             throw error;
         }
     }
     notifyIfStale(result, kind, key) {
-        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.IgnoredStale ||
-            result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.RejectedConflict) {
-            this.metrics?.recordLocationStoreError('compare_exchange');
-        }
         if (result.status !== internal_location_contracts_1.ZLinkLocationWriteStatus.IgnoredStale) {
             return;
         }
@@ -837,10 +850,6 @@ class ZLinkLocationRuntime {
         }
     }
     notifyIfStaleStatus(status, kind, key) {
-        if (status === internal_location_contracts_1.ZLinkLocationWriteStatus.IgnoredStale ||
-            status === internal_location_contracts_1.ZLinkLocationWriteStatus.RejectedConflict) {
-            this.metrics?.recordLocationStoreError('compare_exchange');
-        }
         if (status !== internal_location_contracts_1.ZLinkLocationWriteStatus.IgnoredStale) {
             return;
         }
@@ -848,8 +857,7 @@ class ZLinkLocationRuntime {
             handler({ kind, key });
         }
     }
-    recordFailure(message, operation = 'read') {
-        this.metrics?.recordLocationStoreError(operation);
+    recordFailure(message) {
         this.ownerLeaseHealthy = false;
         this.lastError = message;
     }
@@ -908,8 +916,8 @@ class OwnerLeaseRenewTimeoutError extends Error {
         this.name = 'OwnerLeaseRenewTimeoutError';
     }
 }
-function remainingTimeoutMs(timeoutDeadline) {
-    return Math.max(0, timeoutDeadline - performance.now());
+function remainingTimeoutMs(timeoutStartedAtMs, timeoutMs) {
+    return Math.max(0, timeoutMs - (performance.now() - timeoutStartedAtMs));
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);

package/dist/runtime/messaging/framework-json-v1.d.ts

@@ -1,7 +1,5 @@
-import type { ZLinkJsonSchema } from '../../contracts/Handlers/JsonContract';
+import * as profile from '@zlink-systems/stream-wire/internal/json';
 export declare const FRAMEWORK_JSON_V1_PROFILE = "framework-json-v1";
-export interface FrameworkJsonParseOptions {
-    readonly rejectPropertyName?: (name: string) => boolean;
-}
-export declare function stringifyFrameworkJsonV1(value: unknown, schema?: ZLinkJsonSchema): string;
-export declare function parseFrameworkJsonV1(text: string, options?: FrameworkJsonParseOptions, schema?: ZLinkJsonSchema): unknown;
+export declare const stringifyFrameworkJsonV1: typeof profile.stringifyFrameworkJsonV1;
+export declare const parseFrameworkJsonV1: typeof profile.parseFrameworkJsonV1;
+export type { FrameworkJsonParseOptions } from '@zlink-systems/stream-wire/internal/json';