@zlink-systems/framework 0.10.0

package/dist/runtime/locations/runtime.js

@@ -0,0 +1,792 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLocationRuntime = exports.ZLinkOwnerCleanupError = void 0;
+const Options_1 = require("../../contracts/Locations/Options");
+const EndpointNotation_1 = require("../../contracts/Configuration/EndpointNotation");
+const node_crypto_1 = require("node:crypto");
+const internal_location_contracts_1 = require("./internal-location-contracts");
+const Authority_1 = require("../../contracts/Locations/Authority");
+const authority_key_codec_1 = require("./authority-key-codec");
+const canonical_codec_1 = require("./canonical-codec");
+const key_codec_1 = require("./key-codec");
+const lease_tracker_1 = require("./lease-tracker");
+class ZLinkOwnerCleanupError extends Error {
+    constructor(cause) {
+        super(`Owner cleanup failed: ${errorMessage(cause)}`, { cause });
+        this.name = 'ZLinkOwnerCleanupError';
+    }
+}
+exports.ZLinkOwnerCleanupError = ZLinkOwnerCleanupError;
+class ZLinkLocationRuntime {
+    ownerId;
+    options;
+    stores;
+    events;
+    setTimer;
+    clearTimer;
+    monotonicNowMs;
+    liveRows;
+    ownershipLostHandlers = new Set();
+    ownerLeaseRenewedHandlers = new Set();
+    ownerLeaseRenewalFailedHandlers = new Set();
+    heartbeatTimer;
+    heartbeatRenewal;
+    nodeRidValue;
+    started = false;
+    ownerCleanupComplete = true;
+    metrics;
+    meshNames;
+    leaseScopes;
+    rewriteAuthorityPayloadForOwner;
+    nextLeaseRenewAtMs;
+    ownerToken;
+    lastOwnerToken;
+    ownerLeaseDeadlineMs;
+    ownerLeaseHealthy = false;
+    ownerLeaseRenewedAt;
+    lastError;
+    get ownerLeaseUsable() {
+        return this.ownerLeaseHealthy
+            && (this.ownerLeaseDeadlineMs === undefined
+                || this.monotonicNowMs() < this.ownerLeaseDeadlineMs);
+    }
+    constructor(runtimeOptions) {
+        this.stores = runtimeOptions.stores;
+        this.options = { ...Options_1.zlinkRuntimeDefaultLocationOptions, ...runtimeOptions.options };
+        this.ownerId = runtimeOptions.ownerId ?? (0, node_crypto_1.randomUUID)().replaceAll('-', '');
+        this.events = runtimeOptions.events;
+        this.metrics = runtimeOptions.metrics;
+        this.meshNames = [...new Set(runtimeOptions.meshNames ?? [])];
+        this.leaseScopes = runtimeOptions.leaseScopes ?? this.meshNames.map(name => ({ kind: 'mesh', name }));
+        this.rewriteAuthorityPayloadForOwner = runtimeOptions.rewriteAuthorityPayloadForOwner;
+        this.monotonicNowMs = runtimeOptions.monotonicNowMs ?? (() => performance.now());
+        this.setTimer = runtimeOptions.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.clearTimer = runtimeOptions.clearTimer ?? ((handle) => clearTimeout(handle));
+        const leaseTracker = runtimeOptions.leaseTracker ?? new lease_tracker_1.ZLinkOwnerLeaseTracker({
+            store: this.stores.ownerLeaseStore,
+            options: this.options,
+            monotonicNowMs: this.monotonicNowMs
+        });
+        this.liveRows = new lease_tracker_1.ZLinkLiveRowFilter(leaseTracker);
+    }
+    get isStarted() {
+        return this.started;
+    }
+    get nodeRid() {
+        return this.nodeRidValue;
+    }
+    get currentOwnerToken() {
+        return this.ownerToken;
+    }
+    async reclaimOwnerAuthorities(signal) {
+        const owner = this.ownerToken;
+        if (owner === undefined) {
+            throw new Error('Authority recovery requires a claimed owner token.');
+        }
+        const entries = await this.readAllAuthorityEntries(signal);
+        const failures = [];
+        for (const entry of entries) {
+            const snapshot = entry.snapshot;
+            if (snapshot.ownerId !== owner.ownerId
+                || snapshot.ownerLeaseGeneration === owner.leaseGeneration) {
+                continue;
+            }
+            try {
+                const result = await this.stores.authorityStore.compareExchangeAuthority(entry.key, snapshot.storeVersion, {
+                    kind: 'rebindOwnerLease',
+                    expectedOwner: {
+                        ownerId: snapshot.ownerId,
+                        leaseGeneration: snapshot.ownerLeaseGeneration
+                    },
+                    targetOwner: owner,
+                    payload: Buffer.from(this.rewriteAuthorityPayloadForOwner?.(snapshot.payload, owner)
+                        ?? snapshot.payload)
+                }, signal);
+                if (result.kind === 'stored')
+                    continue;
+                if (result.kind === 'conflict') {
+                    const current = result.current;
+                    if (current.kind === 'snapshot'
+                        && current.ownerId === owner.ownerId
+                        && current.ownerLeaseGeneration === owner.leaseGeneration) {
+                        continue;
+                    }
+                    continue;
+                }
+                failures.push(new Error(`Authority '${entry.key.value}' recovery returned '${result.kind}'.`));
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'One or more authority records failed lease recovery.');
+        }
+    }
+    async readAllAuthorityEntries(signal) {
+        for (;;) {
+            const entries = [];
+            let cursor;
+            let expired = false;
+            do {
+                const page = await this.stores.authorityStore.listAuthorities('', cursor, 1000, signal);
+                if (page.kind === 'scanExpired') {
+                    expired = true;
+                    break;
+                }
+                entries.push(...page.items);
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            if (!expired)
+                return entries;
+        }
+    }
+    addOwnershipLostHandler(handler) {
+        this.ownershipLostHandlers.add(handler);
+    }
+    removeOwnershipLostHandler(handler) {
+        this.ownershipLostHandlers.delete(handler);
+    }
+    addOwnerLeaseRenewedHandler(handler) {
+        this.ownerLeaseRenewedHandlers.add(handler);
+    }
+    removeOwnerLeaseRenewedHandler(handler) {
+        this.ownerLeaseRenewedHandlers.delete(handler);
+    }
+    addOwnerLeaseRenewalFailedHandler(handler) {
+        this.ownerLeaseRenewalFailedHandlers.add(handler);
+    }
+    removeOwnerLeaseRenewalFailedHandler(handler) {
+        this.ownerLeaseRenewalFailedHandlers.delete(handler);
+    }
+    async start(nodeRid, signal) {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.ownerCleanupComplete = false;
+        this.nodeRidValue = nodeRid;
+        const claimStartedAtMs = this.monotonicNowMs();
+        let claim;
+        try {
+            claim = await withTimeout((claimSignal) => this.stores.ownerLeaseStore.claimOwnerLease(this.ownerId, this.options.ownerLeaseTtlMs, claimSignal), this.options.ownerLeaseRenewTimeoutMs, signal);
+        }
+        catch (error) {
+            this.ownerLeaseHealthy = false;
+            this.ownerLeaseDeadlineMs = undefined;
+            if (signal?.aborted === true)
+                throw error;
+            this.recordFailure(errorMessage(error), 'owner_lease_claim');
+            // A Location host can still serve transport work while the Store is
+            // unavailable. Keep the runtime in degraded mode so the heartbeat can
+            // claim a lease after recovery; no descriptor or stateful authority is
+            // published until that claim succeeds.
+            this.nextLeaseRenewAtMs = this.monotonicNowMs();
+            this.scheduleHeartbeat();
+            return;
+        }
+        const claimCompletedAtMs = this.monotonicNowMs();
+        if (claim.kind !== 'claimed') {
+            this.started = false;
+            this.ownerCleanupComplete = true;
+            throw new Error(`Owner lease claim failed with '${claim.kind}'.`);
+        }
+        this.ownerToken = claim.token;
+        this.ownerLeaseHealthy = true;
+        this.ownerLeaseRenewedAt = claim.storeNow;
+        this.setOwnerLeaseDeadline(claimStartedAtMs, claimCompletedAtMs, claim.leaseExpiresAt, claim.storeNow);
+        this.nextLeaseRenewAtMs = this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
+        this.scheduleHeartbeat();
+    }
+    async stop(signal) {
+        if (!this.started && this.ownerCleanupComplete) {
+            return;
+        }
+        this.started = false;
+        if (this.heartbeatTimer !== undefined) {
+            this.clearTimer(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        this.nextLeaseRenewAtMs = undefined;
+        this.ownerLeaseDeadlineMs = undefined;
+        await this.heartbeatRenewal;
+        await this.cleanupOwner(signal);
+    }
+    async cleanupOwner(signal) {
+        if (this.ownerCleanupComplete) {
+            return;
+        }
+        try {
+            const owner = this.ownerToken ?? this.lastOwnerToken ?? {
+                ownerId: this.ownerId,
+                leaseGeneration: 0n
+            };
+            await this.stores.locationStore.removeAllByOwner(owner, signal);
+            const currentLease = await this.stores.ownerLeaseStore.readOwnerLease(this.ownerId, signal);
+            if (currentLease.kind === 'found') {
+                await this.stores.ownerLeaseStore.releaseOwnerLease(currentLease.token, signal);
+            }
+            this.ownerToken = undefined;
+            this.lastOwnerToken = undefined;
+            this.ownerCleanupComplete = true;
+        }
+        catch (error) {
+            this.recordFailure(errorMessage(error));
+            throw new ZLinkOwnerCleanupError(error);
+        }
+    }
+    async renewOwnerLeaseOnce(signal) {
+        if (!this.started) {
+            return false;
+        }
+        if (this.ownerToken === undefined) {
+            return await this.claimFreshOwnerLease(signal);
+        }
+        try {
+            const renewStartedAtMs = this.monotonicNowMs();
+            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') {
+                // The provider may have been restarted with an empty store. The
+                // previous token can no longer be renewed, so the next heartbeat must
+                // perform a fresh claim rather than retrying the stale token forever.
+                this.lastOwnerToken = this.ownerToken;
+                this.ownerToken = undefined;
+                this.ownerLeaseHealthy = false;
+                this.ownerLeaseDeadlineMs = undefined;
+                this.recordFailure('Owner lease token is stale.');
+                for (const handler of this.ownerLeaseRenewalFailedHandlers)
+                    handler();
+                // The store has already told us that this owner token cannot be
+                // renewed. Claim immediately so descriptor recovery does not wait for
+                // another heartbeat interval.
+                return await this.claimFreshOwnerLease(signal);
+            }
+            this.ownerLeaseHealthy = true;
+            this.ownerLeaseRenewedAt = result.storeNow;
+            this.setOwnerLeaseDeadline(renewStartedAtMs, renewCompletedAtMs, result.leaseExpiresAt, result.storeNow);
+            this.lastError = undefined;
+            for (const handler of this.ownerLeaseRenewedHandlers)
+                handler(result);
+            return true;
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                throw error;
+            this.recordOwnerLeaseRenewFailure();
+            this.recordFailure(errorMessage(error), 'lease_renew');
+            for (const handler of this.ownerLeaseRenewalFailedHandlers)
+                handler();
+            return false;
+        }
+    }
+    async claimFreshOwnerLease(signal) {
+        try {
+            const claimStartedAtMs = this.monotonicNowMs();
+            const claim = await withTimeout((claimSignal) => this.stores.ownerLeaseStore.claimOwnerLease(this.ownerId, this.options.ownerLeaseTtlMs, claimSignal), this.options.ownerLeaseRenewTimeoutMs, signal);
+            const claimCompletedAtMs = this.monotonicNowMs();
+            if (claim.kind !== 'claimed') {
+                this.recordFailure(`Owner lease claim failed with '${claim.kind}'.`, 'owner_lease_claim');
+                return false;
+            }
+            if (!this.started) {
+                // stop() may have completed while the Store claim was in flight. Do
+                // not install a token into a stopped runtime or leave an orphan lease.
+                await this.stores.ownerLeaseStore.releaseOwnerLease(claim.token).catch(() => undefined);
+                return false;
+            }
+            this.lastOwnerToken = this.ownerToken;
+            this.ownerToken = claim.token;
+            this.ownerLeaseHealthy = true;
+            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
+                });
+            }
+            return true;
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                throw error;
+            this.recordOwnerLeaseRenewFailure();
+            this.recordFailure(errorMessage(error), 'owner_lease_claim');
+            return false;
+        }
+    }
+    setOwnerLeaseDeadline(requestStartedAtMs, requestCompletedAtMs, leaseExpiresAt, storeNow) {
+        const roundTripMs = Math.max(0, requestCompletedAtMs - requestStartedAtMs);
+        const remainingTtlMs = Math.max(0, leaseExpiresAt.getTime() - storeNow.getTime());
+        // The Store's remaining TTL is measured at an unknown point during the
+        // request. Subtract the full observed round trip and the fencing margin
+        // so local eligibility cannot outlive the conservative pre-request bound.
+        this.ownerLeaseDeadlineMs = requestCompletedAtMs + Math.max(0, remainingTtlMs - roundTripMs - this.options.ownerLeaseFencingMarginMs);
+    }
+    async publishDraining(signal) {
+        try {
+            const peers = await this.stores.peerStore.listPeers({}, signal);
+            for (const peer of peers) {
+                if (peer.ownerId !== this.ownerId || peer.draining)
+                    continue;
+                const result = await this.stores.peerStore.updatePeer({ ...peer, draining: true }, internal_location_contracts_1.ZLinkLocationWriteIntent.Renew, signal);
+                if (result.status !== internal_location_contracts_1.ZLinkLocationWriteStatus.Stored)
+                    return false;
+            }
+            return true;
+        }
+        catch (error) {
+            this.recordFailure(errorMessage(error));
+            return false;
+        }
+    }
+    async writeMeshNode(descriptor, intent, signal) {
+        const owner = this.ownerToken;
+        if (owner === undefined) {
+            throw new Error('MeshNode descriptor write requires a claimed owner token.');
+        }
+        const stamped = {
+            ...descriptor,
+            ownerId: owner.ownerId,
+            leaseGeneration: owner.leaseGeneration,
+            // The canonical opaque descriptor carries the time of this write.
+            // It is part of the stored envelope, so it must be stamped before
+            // handing the descriptor to the provider rather than only on the
+            // in-process result after the write completes.
+            updatedAt: new Date()
+        };
+        let result = await this.guardWrite(() => this.stores.locationStore.updateMeshNode(stamped, intent, 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)) {
+            // A Store restart can remove the descriptor while retaining the
+            // 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));
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Peer, `${descriptor.meshName}\0${String(descriptor.rid)}`);
+        return result;
+    }
+    async writePeer(peer, intent, signal) {
+        (0, canonical_codec_1.zlinkLocationAutoConnectTypeName)(peer.autoConnectType);
+        (0, canonical_codec_1.zlinkLocationRoleName)(peer.role);
+        // Normalize on write, not just on listPeerLocations()'s read: the row
+        // key is derived from this same endpoint, and a caller round-tripping a
+        // row it just read (e.g. to remove it) must compute the same key the
+        // row was stored under.
+        const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(peer.endpoint);
+        const stamped = { ...peer, endpoint: normalizedEndpoint, ownerId: this.ownerId };
+        const result = await this.guardWrite(() => this.stores.peerStore.updatePeer(stamped, intent, signal));
+        const key = {
+            autoConnectType: peer.autoConnectType,
+            meshName: peer.meshName,
+            role: peer.role,
+            nodeRid: peer.nodeRid,
+            endpoint: normalizedEndpoint
+        };
+        const rowKey = key_codec_1.ZLinkLocationKeyCodec.encodePeerKey(key);
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.peerRowUpdated({ kind: internal_location_contracts_1.ZLinkLocationKind.Peer, key }, { ...stamped, generation: result.generation, updatedAt: result.updatedAt });
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Peer, rowKey);
+        return result;
+    }
+    async writeSpot(spot, intent, signal) {
+        const owner = this.ownerToken;
+        if (owner === undefined)
+            throw new Error('Spot location write requires a claimed owner token.');
+        const stamped = { ...spot, ownerId: owner.ownerId, leaseGeneration: owner.leaseGeneration };
+        const result = await this.guardWrite(() => this.stores.spotStore.updateSpot(stamped, intent, signal));
+        const key = { meshName: spot.meshName, spotId: spot.spotId };
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.spotRowUpdated(key, { ...stamped, updatedAt: result.updatedAt });
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Spot, key_codec_1.ZLinkLocationKeyCodec.encodeSpotKey(key));
+        return result;
+    }
+    async writeActor(actor, intent, signal) {
+        const owner = this.ownerToken;
+        if (owner === undefined)
+            throw new Error('Actor location write requires a claimed owner token.');
+        const stamped = {
+            ...actor,
+            actorType: actor.actorType,
+            ownerId: owner.ownerId,
+            leaseGeneration: owner.leaseGeneration
+        };
+        const result = await this.guardWrite(() => this.stores.actorStore.updateActor(stamped, intent, signal));
+        const key = { meshName: stamped.meshName, actorId: stamped.actorId };
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.actorRowUpdated(key, { ...stamped, updatedAt: result.updatedAt });
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Actor, key_codec_1.ZLinkLocationKeyCodec.encodeActorKey(key));
+        return result;
+    }
+    async writeRoute(route, intent, signal) {
+        const stamped = { ...route, ownerId: this.ownerId };
+        const result = await this.guardWrite(() => this.stores.routeStore.updateRoute(stamped, intent, signal));
+        const key = { routeKind: route.routeKind, routeKey: route.routeKey };
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.routeRowUpdated(key, { ...stamped, generation: result.generation, updatedAt: result.updatedAt });
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Route, key_codec_1.ZLinkLocationKeyCodec.encodeRouteKey(key));
+        return result;
+    }
+    async removePeer(key, generation, signal) {
+        const result = await this.guardWrite(() => this.stores.peerStore.removePeer(key, { ownerId: this.ownerId, leaseGeneration: generation }, signal));
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.peerRowRemoved({ kind: internal_location_contracts_1.ZLinkLocationKind.Peer, key });
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Peer, key_codec_1.ZLinkLocationKeyCodec.encodePeerKey(key));
+        return result;
+    }
+    async removeSpot(key, generation, signal) {
+        const status = await this.guardStatusWrite(() => this.stores.spotStore.removeSpot(key, { ownerId: this.ownerId, leaseGeneration: generation }, signal));
+        if (status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.spotRowRemoved(key);
+        }
+        this.notifyIfStaleStatus(status, internal_location_contracts_1.ZLinkLocationKind.Spot, key_codec_1.ZLinkLocationKeyCodec.encodeSpotKey(key));
+        return status;
+    }
+    async removeActor(key, generation, signal) {
+        const status = await this.guardStatusWrite(() => this.stores.actorStore.removeActor(key, { ownerId: this.ownerId, leaseGeneration: generation }, signal));
+        if (status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.actorRowRemoved(key);
+        }
+        this.notifyIfStaleStatus(status, internal_location_contracts_1.ZLinkLocationKind.Actor, key_codec_1.ZLinkLocationKeyCodec.encodeActorKey(key));
+        return status;
+    }
+    async removeRoute(key, generation, signal) {
+        const result = await this.guardWrite(() => this.stores.routeStore.removeRoute(key, { ownerId: this.ownerId, leaseGeneration: generation }, signal));
+        if (result.status === internal_location_contracts_1.ZLinkLocationWriteStatus.Stored) {
+            this.events?.routeRowRemoved(key);
+        }
+        this.notifyIfStale(result, internal_location_contracts_1.ZLinkLocationKind.Route, key_codec_1.ZLinkLocationKeyCodec.encodeRouteKey(key));
+        return result;
+    }
+    async getStatus() {
+        return {
+            storeHealthy: this.lastError === undefined,
+            watchEnabled: false,
+            pollingIntervalMs: this.options.pollingIntervalMs,
+            lastRefreshAt: this.ownerLeaseRenewedAt,
+            lastError: this.lastError,
+            ownerLeaseHealthy: this.ownerLeaseUsable,
+            ownerLeaseRenewedAt: this.ownerLeaseRenewedAt
+        };
+    }
+    reportDiscoveryFailure(error) {
+        this.recordFailure(errorMessage(error), 'read');
+    }
+    async listPeerLocations(filter, signal) {
+        const rows = await this.stores.peerStore.listPeers(filter, signal);
+        const live = await this.filterLive(rows, (row) => row.ownerId, signal);
+        // Location Store rows may have been written before this process adopted
+        // the endpoint-notation policy, or by another language/version's writer.
+        // Normalize on read so every comparison downstream sees the canonical
+        // form regardless of what the store actually holds.
+        return live.map((row) => ({ ...row, endpoint: (0, EndpointNotation_1.normalizeEndpoint)(row.endpoint) }));
+    }
+    async listLiveMeshNodes(meshName, signal) {
+        const rows = (await this.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items;
+        const live = await this.filterLive(rows, (row) => row.ownerId, signal);
+        return live.map((row) => ({ ...row, endpoint: (0, EndpointNotation_1.normalizeEndpoint)(row.endpoint) }));
+    }
+    async listMeshNodeDescriptors(meshName, page, signal) {
+        const rows = await this.stores.locationStore.listMeshNodes(meshName, this.pageRequest(page), signal);
+        const live = await this.filterLive(rows.items, (row) => row.ownerId, signal);
+        return {
+            items: live.map((row) => ({ ...row, endpoint: (0, EndpointNotation_1.normalizeEndpoint)(row.endpoint) })),
+            continuationToken: rows.continuationToken
+        };
+    }
+    async listSpotLocations(filter, page, signal) {
+        const queryStore = this.stores.spotStore;
+        if (queryStore.listSpots === undefined) {
+            throw new Error('The configured Spot location store does not provide operational list queries.');
+        }
+        const rows = await queryStore.listSpots(filter, this.pageRequest(page), signal);
+        return {
+            items: await this.filterLive(rows.items, (row) => row.ownerId, signal),
+            continuationToken: rows.continuationToken
+        };
+    }
+    async listActorLocations(filter, page, signal) {
+        const queryStore = this.stores.actorStore;
+        if (queryStore.listActors === undefined) {
+            throw new Error('The configured Actor location store does not provide operational list queries.');
+        }
+        const rows = await queryStore.listActors(filter, this.pageRequest(page), signal);
+        return {
+            items: await this.filterLive(rows.items, (row) => row.ownerId, signal),
+            continuationToken: rows.continuationToken
+        };
+    }
+    async listObjectLocations(filter, page = {}, signal) {
+        const normalizedPage = this.pageRequest(page);
+        const pageSize = normalizedPage.pageSize ?? this.options.listPageSize;
+        const requestedCursor = normalizedPage.continuationToken;
+        let cursor = requestedCursor === undefined
+            ? undefined
+            : Authority_1.ZLinkAuthorityScanCursor.from(requestedCursor);
+        const items = [];
+        for (;;) {
+            // Keep the Store cursor at the public page boundary. Scanning 1000 rows
+            // and returning only a smaller page would discard the unreturned rows.
+            const result = await this.stores.authorityStore.listAuthorities('', cursor, pageSize, signal);
+            if (result.kind === 'scanExpired') {
+                throw new Error('The authority query snapshot expired.');
+            }
+            for (const entry of result.items) {
+                const identity = (0, authority_key_codec_1.decodeAuthorityKey)(entry.key);
+                const allocation = entry.snapshot.allocation;
+                if (allocation.objectKind !== filter.objectKind
+                    || (filter.stableType !== undefined && allocation.stableType !== filter.stableType)
+                    || (filter.meshName !== undefined && allocation.descriptor.meshName !== filter.meshName))
+                    continue;
+                const live = await this.liveRows.resolve(entry, (candidate) => candidate.snapshot.ownerId, signal) !== undefined;
+                items.push(this.objectLocationEntry(identity.globalId, entry.snapshot, live));
+                if (items.length >= pageSize)
+                    break;
+            }
+            const nextCursor = result.nextCursor;
+            if (items.length >= pageSize || nextCursor === undefined) {
+                return {
+                    items,
+                    continuationToken: nextCursor?.encoded
+                };
+            }
+            cursor = nextCursor;
+        }
+    }
+    async findActorLocation(actorId, signal) {
+        return await this.findObjectLocation('actor', String(actorId), signal);
+    }
+    async findSpotLocation(spotId, signal) {
+        const found = await this.stores.authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('user_spot', String(spotId)), signal);
+        if (found.kind === 'missing' || found.allocation.objectKind === 'actor')
+            return undefined;
+        const live = await this.liveRows.resolve(found, (snapshot) => snapshot.ownerId, signal)
+            !== undefined;
+        return this.objectLocationEntry(String(spotId), found, live);
+    }
+    async findObjectLocation(kind, globalId, signal) {
+        const found = await this.stores.authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)(kind, globalId), signal);
+        if (found.kind === 'missing' || found.allocation.objectKind !== kind)
+            return undefined;
+        const live = await this.liveRows.resolve(found, (snapshot) => snapshot.ownerId, signal)
+            !== undefined;
+        return this.objectLocationEntry(globalId, found, live);
+    }
+    objectLocationEntry(globalId, snapshot, ownerLive) {
+        const allocation = snapshot.allocation;
+        return {
+            globalId,
+            objectGeneration: snapshot.objectGeneration,
+            meshName: allocation.descriptor.meshName,
+            nodeRid: allocation.descriptor.rid,
+            state: allocation.state === 'reserved'
+                ? 'creating'
+                : ownerLive ? 'ready' : 'unavailable',
+            stableType: allocation.stableType
+        };
+    }
+    async listRouteLocations(filter, page, signal) {
+        const rows = await this.stores.routeStore.listRoutes(filter, this.pageRequest(page), signal);
+        return {
+            items: await this.filterLive(rows.items, (row) => row.ownerId, signal),
+            continuationToken: rows.continuationToken
+        };
+    }
+    async listTopology(filter, page, signal) {
+        const entries = [];
+        for (const meshName of this.meshNamesOf(filter.meshName)) {
+            for (const descriptor of await this.listAllMeshNodeDescriptors(meshName, signal)) {
+                const live = (await this.filterLive([descriptor], row => row.ownerId, signal)).length > 0;
+                const entry = {
+                    meshName: descriptor.meshName,
+                    nodeRid: descriptor.rid,
+                    endpoint: descriptor.endpoint,
+                    //  Spec 13 §365는 relocate가 unit seal을 마치면 source가 draining으로
+                    //  넘어간다고 정하고, §409는 draining node가 새 placement target이 되지
+                    //  않는다고 정한다. Host lifecycle의 `Draining`만 보면 relocate로 빠지는
+                    //  node가 계속 accepting으로 보인다.
+                    draining: descriptor.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Draining
+                        || descriptor.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Relocating
+                        || descriptor.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Relocated,
+                    state: live ? internal_location_contracts_1.ZLinkLocationTopologyState.Ready : internal_location_contracts_1.ZLinkLocationTopologyState.Lost,
+                    updatedAt: descriptor.updatedAt
+                };
+                if ((filter.nodeRid === undefined || entry.nodeRid === filter.nodeRid)
+                    && (filter.state === undefined || entry.state === filter.state)) {
+                    entries.push(entry);
+                }
+            }
+        }
+        return this.pageInMemory(entries, page);
+    }
+    pageRequest(page) {
+        return page?.pageSize === undefined
+            ? { ...page, pageSize: this.options.listPageSize }
+            : page;
+    }
+    async listServiceSummaries(filter, page, signal) {
+        const summaries = [];
+        for (const meshName of this.meshNamesOf(filter.meshName)) {
+            const descriptors = await this.listAllMeshNodeDescriptors(meshName, signal);
+            if (descriptors.length === 0)
+                continue;
+            const live = await this.filterLive(descriptors, row => row.ownerId, signal);
+            const liveOwners = new Set(live.map(row => row.ownerId));
+            summaries.push({
+                meshName,
+                totalCount: descriptors.length,
+                readyCount: descriptors.filter(row => liveOwners.has(row.ownerId)).length,
+                errorCount: 0,
+                stoppedCount: descriptors.filter(row => !liveOwners.has(row.ownerId)).length,
+                lastUpdatedAt: descriptors.reduce((latest, row) => row.updatedAt > latest ? row.updatedAt : latest, descriptors[0].updatedAt)
+            });
+        }
+        return this.pageInMemory(summaries, page);
+    }
+    meshNamesOf(meshName) {
+        return meshName === undefined ? this.meshNames : [meshName];
+    }
+    async listAllMeshNodeDescriptors(meshName, signal) {
+        const rows = [];
+        let continuationToken;
+        do {
+            const result = await this.stores.locationStore.listMeshNodes(meshName, { pageSize: this.options.listPageSize, continuationToken }, signal);
+            rows.push(...result.items);
+            continuationToken = result.continuationToken;
+        } while (continuationToken !== undefined);
+        return rows;
+    }
+    pageInMemory(entries, page) {
+        const normalized = this.pageRequest(page);
+        const parsedOffset = Number.parseInt(normalized.continuationToken ?? '0', 10);
+        const offset = Number.isFinite(parsedOffset) && parsedOffset >= 0 ? parsedOffset : 0;
+        const pageSize = normalized.pageSize ?? this.options.listPageSize;
+        const items = entries.slice(offset, offset + pageSize);
+        const nextOffset = offset + items.length;
+        return {
+            items,
+            continuationToken: nextOffset < entries.length ? String(nextOffset) : undefined
+        };
+    }
+    async filterLive(rows, ownerIdOf, signal) {
+        return await this.liveRows.filter(rows, ownerIdOf, signal);
+    }
+    scheduleHeartbeat() {
+        if (!this.started) {
+            return;
+        }
+        const scheduledAt = this.nextLeaseRenewAtMs
+            ?? this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
+        const delayMs = Math.max(0, scheduledAt - this.monotonicNowMs());
+        this.heartbeatTimer = this.setTimer(() => {
+            this.heartbeatTimer = undefined;
+            const lateness = Math.max(0, this.monotonicNowMs() - scheduledAt) / 1000;
+            for (const scope of this.leaseScopes) {
+                this.metrics?.recordOwnerLeaseRenewLateness(lateness, scope.kind, scope.name);
+            }
+            this.nextLeaseRenewAtMs = scheduledAt + this.options.ownerLeaseRenewIntervalMs;
+            if (this.ownerLeaseDeadlineMs !== undefined
+                && this.monotonicNowMs() >= this.ownerLeaseDeadlineMs) {
+                this.ownerLeaseHealthy = false;
+                this.recordFailure('Owner lease expired before renewal completed.', 'lease_expired');
+                for (const handler of this.ownerLeaseRenewalFailedHandlers)
+                    handler();
+            }
+            const renewal = this.renewOwnerLeaseOnce().then(() => undefined, () => undefined).finally(() => {
+                if (this.heartbeatRenewal === renewal) {
+                    this.heartbeatRenewal = undefined;
+                }
+                this.scheduleHeartbeat();
+            });
+            this.heartbeatRenewal = renewal;
+            void renewal;
+        }, delayMs);
+    }
+    async guardWrite(write) {
+        try {
+            return await write();
+        }
+        catch (error) {
+            this.recordFailure(errorMessage(error), 'compare_exchange');
+            throw error;
+        }
+    }
+    async guardStatusWrite(write) {
+        try {
+            return await write();
+        }
+        catch (error) {
+            this.recordFailure(errorMessage(error), 'compare_exchange');
+            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;
+        }
+        for (const handler of this.ownershipLostHandlers) {
+            handler({ kind, key });
+        }
+    }
+    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;
+        }
+        for (const handler of this.ownershipLostHandlers) {
+            handler({ kind, key });
+        }
+    }
+    recordFailure(message, operation = 'read') {
+        this.metrics?.recordLocationStoreError(operation);
+        this.ownerLeaseHealthy = false;
+        this.lastError = message;
+    }
+    recordOwnerLeaseRenewFailure() {
+        for (const scope of this.leaseScopes) {
+            this.metrics?.recordOwnerLeaseRenewFailure(scope.kind, scope.name);
+        }
+    }
+}
+exports.ZLinkLocationRuntime = ZLinkLocationRuntime;
+async function withTimeout(action, timeoutMs, signal) {
+    const timeoutController = new AbortController();
+    const operationSignal = signal === undefined
+        ? timeoutController.signal
+        : AbortSignal.any([signal, timeoutController.signal]);
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            const error = new Error(`Owner lease renewal exceeded ${timeoutMs}ms.`);
+            timeoutController.abort(error);
+            reject(error);
+        }, timeoutMs);
+        timeout.unref();
+    });
+    try {
+        return await Promise.race([action(operationSignal), deadline]);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}