@zlink-systems/framework 0.10.0

package/dist/runtime/locations/in-memory-provider-location-store.d.ts

@@ -0,0 +1,19 @@
+import type { ZLinkLocationStore, ZLinkStoreKey, ZLinkStoreReadResult, ZLinkStoreScanRequest, ZLinkStoreScanResult, ZLinkStoreVersion, ZLinkStoreWriteRequest, ZLinkStoreWriteResult } from '../../contracts';
+/**
+ * Framework-owned primitive Store used by the explicit in-memory option.
+ * Domain records are encoded by ZLinkLocationStoreRepository.
+ */
+export declare class ZLinkInMemoryProviderLocationStore implements ZLinkLocationStore {
+    private readonly now;
+    private readonly values;
+    private readonly scans;
+    private nextVersion;
+    private nextScan;
+    constructor(now?: () => Date);
+    read(key: ZLinkStoreKey, signal?: AbortSignal): Promise<ZLinkStoreReadResult>;
+    write(request: ZLinkStoreWriteRequest, signal?: AbortSignal): Promise<ZLinkStoreWriteResult>;
+    scan(request: ZLinkStoreScanRequest, signal?: AbortSignal): Promise<ZLinkStoreScanResult>;
+    private liveValue;
+}
+export declare function storeKey(value: string): ZLinkStoreKey;
+export declare function storeVersion(value: string): ZLinkStoreVersion;

package/dist/runtime/locations/in-memory-provider-location-store.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkInMemoryProviderLocationStore = void 0;
+exports.storeKey = storeKey;
+exports.storeVersion = storeVersion;
+/**
+ * Framework-owned primitive Store used by the explicit in-memory option.
+ * Domain records are encoded by ZLinkLocationStoreRepository.
+ */
+class ZLinkInMemoryProviderLocationStore {
+    now;
+    values = new Map();
+    scans = new Map();
+    nextVersion = 0n;
+    nextScan = 0n;
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    async read(key, signal) {
+        signal?.throwIfAborted();
+        const storeNow = this.now();
+        const value = this.liveValue(key.value, storeNow);
+        if (value === undefined)
+            return { kind: 'missing', storeNow };
+        return {
+            kind: 'found',
+            value: {
+                bytes: value.bytes.slice(),
+                version: value.version,
+                expiresAt: value.expiresAt,
+                storeNow
+            }
+        };
+    }
+    async write(request, signal) {
+        signal?.throwIfAborted();
+        requireWriteRequest(request);
+        const storeNow = this.now();
+        for (const condition of request.conditions) {
+            const current = this.liveValue(condition.key.value, storeNow);
+            if (condition.kind === 'missing') {
+                if (current !== undefined)
+                    return { kind: 'conflict', storeNow };
+            }
+            else if (current?.version.value !== condition.expected.value) {
+                return { kind: 'conflict', storeNow };
+            }
+        }
+        const putVersions = [];
+        for (const mutation of request.mutations) {
+            if (mutation.kind === 'delete') {
+                this.values.delete(mutation.key.value);
+                continue;
+            }
+            requireValue(mutation.bytes, mutation.retentionMs);
+            const version = storeVersion((++this.nextVersion).toString());
+            const expiresAt = mutation.retentionMs === undefined
+                ? undefined
+                : new Date(storeNow.getTime() + mutation.retentionMs);
+            this.values.set(mutation.key.value, {
+                bytes: mutation.bytes.slice(),
+                version,
+                expiresAt
+            });
+            putVersions.push({ key: mutation.key, version });
+        }
+        return { kind: 'applied', putVersions, storeNow };
+    }
+    async scan(request, signal) {
+        signal?.throwIfAborted();
+        requireScanRequest(request);
+        const storeNow = this.now();
+        let snapshotId;
+        let offset;
+        let snapshot;
+        if (request.cursor === undefined) {
+            snapshotId = (++this.nextScan).toString();
+            offset = 0;
+            snapshot = {
+                items: [...this.values.entries()]
+                    .filter(([key]) => key.startsWith(request.prefix))
+                    .map(([key, value]) => ({ key: storeKey(key), value }))
+                    .filter(item => this.liveValue(item.key.value, storeNow) !== undefined)
+                    .sort((left, right) => left.key.value.localeCompare(right.key.value))
+            };
+            this.scans.set(snapshotId, snapshot);
+        }
+        else {
+            [snapshotId, offset] = parseCursor(request.cursor);
+            snapshot = this.scans.get(snapshotId);
+            if (snapshot === undefined)
+                return { kind: 'expired' };
+        }
+        const selected = snapshot.items.slice(offset, offset + request.limit);
+        const nextOffset = offset + selected.length;
+        const nextCursor = nextOffset < snapshot.items.length
+            ? scanCursor(`${snapshotId}:${nextOffset}`)
+            : undefined;
+        if (nextCursor === undefined)
+            this.scans.delete(snapshotId);
+        return {
+            kind: 'page',
+            value: {
+                items: selected.map(item => ({
+                    key: item.key,
+                    value: {
+                        bytes: item.value.bytes.slice(),
+                        version: item.value.version,
+                        expiresAt: item.value.expiresAt,
+                        storeNow
+                    }
+                })),
+                nextCursor,
+                storeNow
+            }
+        };
+    }
+    liveValue(key, storeNow) {
+        const value = this.values.get(key);
+        if (value?.expiresAt !== undefined && value.expiresAt.getTime() <= storeNow.getTime()) {
+            this.values.delete(key);
+            return undefined;
+        }
+        return value;
+    }
+}
+exports.ZLinkInMemoryProviderLocationStore = ZLinkInMemoryProviderLocationStore;
+function storeKey(value) {
+    return { value };
+}
+function storeVersion(value) {
+    return { value };
+}
+function scanCursor(value) {
+    return { value };
+}
+function parseCursor(cursor) {
+    const separator = cursor.value.indexOf(':');
+    const snapshotId = cursor.value.slice(0, separator);
+    const offset = Number(cursor.value.slice(separator + 1));
+    if (separator < 1 || !Number.isSafeInteger(offset) || offset < 0) {
+        throw new RangeError('Location Store scan cursor is invalid.');
+    }
+    return [snapshotId, offset];
+}
+function requireWriteRequest(request) {
+    const conditionKeys = request.conditions.map(condition => condition.key.value);
+    const mutationKeys = request.mutations.map(mutation => mutation.key.value);
+    const keys = [...new Set([...conditionKeys, ...mutationKeys])];
+    if (new Set(conditionKeys).size !== conditionKeys.length
+        || new Set(mutationKeys).size !== mutationKeys.length
+        || keys.length > 2_048) {
+        throw new RangeError('Location Store write keys must be unique and bounded to 2,048.');
+    }
+    for (const key of keys)
+        requireKey(key);
+    const encodedSize = request.mutations.reduce((sum, mutation) => sum + (mutation.kind === 'put' ? mutation.bytes.byteLength : 0), 0);
+    if (encodedSize > 4 * 1024 * 1024) {
+        throw new RangeError('Location Store write exceeds 4 MiB.');
+    }
+}
+function requireScanRequest(request) {
+    if (Buffer.byteLength(request.prefix, 'utf8') > 1_024) {
+        throw new RangeError('Location Store scan prefix exceeds 1,024 UTF-8 bytes.');
+    }
+    if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 1_000) {
+        throw new RangeError('Location Store scan limit must be in 1..1000.');
+    }
+}
+function requireValue(bytes, retentionMs) {
+    if (bytes.byteLength > 1024 * 1024) {
+        throw new RangeError('Location Store value exceeds 1 MiB.');
+    }
+    if (retentionMs !== undefined && (!Number.isSafeInteger(retentionMs) || retentionMs < 1)) {
+        throw new RangeError('Location Store retention must be a positive safe integer.');
+    }
+}
+function requireKey(value) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 1_024) {
+        throw new RangeError('Location Store key must contain 1..1,024 UTF-8 bytes.');
+    }
+}

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

@@ -0,0 +1,11 @@
+export * from './auto-connect';
+export * from './aggregate-inventory-store';
+export * from './domain-store-contract';
+export * from './in-memory-location-store';
+export * from './in-memory-provider-location-store';
+export * from './location-store-repository';
+export * from './in-memory-authority-store';
+export * from './lease-tracker';
+export * from './lifecycle';
+export * from './resolvers';
+export * from './runtime';

package/dist/runtime/locations/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auto-connect"), exports);
+__exportStar(require("./aggregate-inventory-store"), exports);
+__exportStar(require("./domain-store-contract"), exports);
+__exportStar(require("./in-memory-location-store"), exports);
+__exportStar(require("./in-memory-provider-location-store"), exports);
+__exportStar(require("./location-store-repository"), exports);
+__exportStar(require("./in-memory-authority-store"), exports);
+__exportStar(require("./lease-tracker"), exports);
+__exportStar(require("./lifecycle"), exports);
+__exportStar(require("./resolvers"), exports);
+__exportStar(require("./runtime"), exports);

package/dist/runtime/locations/internal-location-contracts.d.ts

@@ -0,0 +1,7 @@
+export * from '../../contracts/Locations';
+export type * from '../../contracts/Locations/Authority';
+export type { ZLinkActorLocation, ZLinkPeerLocation, ZLinkRouteLocation, ZLinkSpotLocation } from '../../contracts/Locations/Rows';
+export type { ZLinkActorLocationFilter, ZLinkActorLocationKey, ZLinkLocationKey, ZLinkPeerLocationFilter, ZLinkPeerLocationKey, ZLinkRouteLocationFilter, ZLinkRouteLocationKey, ZLinkSpotLocationFilter, ZLinkSpotLocationKey } from '../../contracts/Locations/Keys';
+export { ZLinkLocationAutoConnectType, ZLinkRouteKind } from '../../contracts/Locations/Values';
+export type { ZLinkPeerLocationResolver } from '../../contracts/Locations/Resolvers';
+export type { ZLinkLocationChangeStampScope } from '../../contracts/Locations/Watch';

package/dist/runtime/locations/internal-location-contracts.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRouteKind = exports.ZLinkLocationAutoConnectType = void 0;
+__exportStar(require("../../contracts/Locations"), exports);
+var Values_1 = require("../../contracts/Locations/Values");
+Object.defineProperty(exports, "ZLinkLocationAutoConnectType", { enumerable: true, get: function () { return Values_1.ZLinkLocationAutoConnectType; } });
+Object.defineProperty(exports, "ZLinkRouteKind", { enumerable: true, get: function () { return Values_1.ZLinkRouteKind; } });

package/dist/runtime/locations/internal-store-contracts.d.ts

@@ -0,0 +1,35 @@
+import type { ZLinkActorLocation, ZLinkActorLocationFilter, ZLinkActorLocationKey, ZLinkLocationOwnerToken, ZLinkLocationPage, ZLinkLocationWriteIntent, ZLinkLocationWriteResult, ZLinkLocationWriteStatus, ZLinkPageRequest, ZLinkPeerLocation, ZLinkPeerLocationFilter, ZLinkPeerLocationKey, ZLinkRouteLocation, ZLinkRouteLocationFilter, ZLinkRouteLocationKey, ZLinkSpotLocation, ZLinkSpotLocationFilter, ZLinkSpotLocationKey } from './internal-location-contracts';
+import type { ZLinkDomainLocationStore } from './domain-store-contract';
+export type ZLinkAuthorityStore = Pick<ZLinkDomainLocationStore, 'readAuthority' | 'compareExchangeAuthority' | 'listAuthorities'>;
+export type ZLinkObjectCreationStore = Pick<ZLinkDomainLocationStore, 'readCreationTerminal' | 'reserve' | 'commit' | 'completeCreation' | 'abort' | 'prepareAggregate' | 'commitAggregate' | 'abortAggregate'>;
+export type ZLinkOwnerLeaseStore = Pick<ZLinkDomainLocationStore, 'claimOwnerLease' | 'readOwnerLease' | 'renewOwnerLease' | 'releaseOwnerLease'>;
+export type ZLinkMeshNodeLocationStore = Pick<ZLinkDomainLocationStore, 'updateMeshNode' | 'removeMeshNode' | 'listMeshNodes'>;
+export type ZLinkClientServerLocationStore = Pick<ZLinkDomainLocationStore, 'updateClientServer' | 'removeClientServer' | 'listClientServers'>;
+export type ZLinkFanoutLocationStore = Pick<ZLinkDomainLocationStore, 'updateFanoutPublisher' | 'removeFanoutPublisher' | 'listFanoutPublishers'>;
+export interface ZLinkPeerLocationStore {
+    updatePeer(peer: ZLinkPeerLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    removePeer(key: ZLinkPeerLocationKey, owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    listPeers(filter: ZLinkPeerLocationFilter, signal?: AbortSignal): Promise<readonly ZLinkPeerLocation[]>;
+}
+export interface ZLinkSpotLocationStore {
+    updateSpot(location: ZLinkSpotLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    removeSpot(key: ZLinkSpotLocationKey, owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<ZLinkLocationWriteStatus>;
+    resolveSpot(key: ZLinkSpotLocationKey, signal?: AbortSignal): Promise<ZLinkSpotLocation | undefined>;
+}
+export interface ZLinkSpotLocationQueryStore {
+    listSpots(filter: ZLinkSpotLocationFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkSpotLocation>>;
+}
+export interface ZLinkActorLocationStore {
+    updateActor(location: ZLinkActorLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    removeActor(key: ZLinkActorLocationKey, owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<ZLinkLocationWriteStatus>;
+    resolveActor(key: ZLinkActorLocationKey, signal?: AbortSignal): Promise<ZLinkActorLocation | undefined>;
+}
+export interface ZLinkActorLocationQueryStore {
+    listActors(filter: ZLinkActorLocationFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkActorLocation>>;
+}
+export interface ZLinkRouteLocationStore {
+    updateRoute(route: ZLinkRouteLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    removeRoute(key: ZLinkRouteLocationKey, owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    resolveRoute(key: ZLinkRouteLocationKey, signal?: AbortSignal): Promise<ZLinkRouteLocation | undefined>;
+    listRoutes(filter: ZLinkRouteLocationFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkRouteLocation>>;
+}

package/dist/runtime/locations/internal-store-contracts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/locations/key-codec.d.ts

@@ -0,0 +1,13 @@
+import type { RoutingId } from '../../contracts/Common';
+import { type ZLinkActorLocationKey, type ZLinkPeerLocationKey, type ZLinkRouteLocationKey, type ZLinkSpotLocationKey } from './internal-location-contracts';
+export declare const ZLinkLocationKeyCodec: Readonly<{
+    encodePeerKey(key: ZLinkPeerLocationKey): string;
+    encodeSpotKey(key: ZLinkSpotLocationKey): string;
+    encodeActorKey(key: ZLinkActorLocationKey): string;
+    encodeRouteKey(key: ZLinkRouteLocationKey): string;
+    encodeRoutingIdHex: typeof encodeRoutingIdHex;
+    normalizeActorType: typeof normalizeActorType;
+}>;
+declare function normalizeActorType(actorType: string | undefined): string;
+declare function encodeRoutingIdHex(routingId: RoutingId): string;
+export {};

package/dist/runtime/locations/key-codec.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLocationKeyCodec = void 0;
+const canonical_codec_1 = require("./canonical-codec");
+const routing_id_1 = require("../routing-id");
+// Framework bookkeeping codec for in-memory row maps and generation guards.
+// Backend extensions keep their own storage codec so transport key layout
+// changes do not leak into runtime models.
+exports.ZLinkLocationKeyCodec = Object.freeze({
+    encodePeerKey(key) {
+        const identity = key.nodeRid === undefined ? key.endpoint ?? '' : encodeRoutingIdHex(key.nodeRid);
+        return encodeSegments((0, canonical_codec_1.zlinkLocationAutoConnectTypeName)(key.autoConnectType), key.meshName, (0, canonical_codec_1.zlinkLocationRoleName)(key.role), identity);
+    },
+    encodeSpotKey(key) {
+        return encodeSegments(key.meshName, requireSpotId(key.spotId));
+    },
+    encodeActorKey(key) {
+        return encodeSegments(key.meshName, key.actorId);
+    },
+    encodeRouteKey(key) {
+        return encodeSegments(String(key.routeKind), key.routeKey);
+    },
+    encodeRoutingIdHex,
+    normalizeActorType
+});
+function normalizeActorType(actorType) {
+    return actorType ?? '';
+}
+function encodeSegments(...segments) {
+    return segments.map((segment) => `${Buffer.byteLength(segment, 'utf8')}:${segment}`).join('');
+}
+function requireSpotId(value) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 255) {
+        throw new TypeError('SpotId must contain 1..255 UTF-8 bytes.');
+    }
+    return value;
+}
+function encodeRoutingIdHex(routingId) {
+    return (0, routing_id_1.encodeRoutingIdStorageHex)(routingId);
+}

package/dist/runtime/locations/lease-tracker.d.ts

@@ -0,0 +1,36 @@
+import { type ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import { type ZLinkLocationOwnerToken } from './internal-location-contracts';
+import type { ZLinkOwnerLeaseStore } from './internal-store-contracts';
+export interface ZLinkOwnerLeaseTrackerOptions {
+    readonly store: ZLinkOwnerLeaseStore;
+    readonly options?: ZLinkLocationOptionOverrides;
+    readonly monotonicNowMs?: () => number;
+}
+export declare class ZLinkOwnerLeaseTracker {
+    private readonly lane;
+    private readonly store;
+    private readonly options;
+    private readonly monotonicNowMs;
+    private readonly snapshots;
+    private readonly refreshes;
+    private liveOwnerFingerprint?;
+    private liveOwnerVersion;
+    constructor(options: ZLinkOwnerLeaseTrackerOptions);
+    isOwnerLive(ownerId: string, signal?: AbortSignal): Promise<boolean>;
+    remainingLeaseMs(ownerId: string, signal?: AbortSignal): Promise<number>;
+    remainingOwnerTokenLeaseMs(owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<number>;
+    getLiveOwnerSetVersion(signal?: AbortSignal): Promise<number>;
+    private getSnapshot;
+    private prepareSnapshotRefresh;
+    private refreshSnapshot;
+    private completeSnapshotRefresh;
+    private failSnapshotRefresh;
+    private isLive;
+}
+export declare class ZLinkLiveRowFilter {
+    private readonly leaseTracker;
+    constructor(leaseTracker: ZLinkOwnerLeaseTracker);
+    filter<TRow>(rows: readonly TRow[], ownerIdOf: (row: TRow) => string, signal?: AbortSignal, include?: (row: TRow) => boolean): Promise<TRow[]>;
+    resolve<TRow>(row: TRow | undefined, ownerIdOf: (row: TRow) => string, signal?: AbortSignal, include?: (row: TRow) => boolean): Promise<TRow | undefined>;
+    private isLive;
+}

package/dist/runtime/locations/lease-tracker.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLiveRowFilter = exports.ZLinkOwnerLeaseTracker = void 0;
+const Options_1 = require("../../contracts/Locations/Options");
+const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("../execution/state-lane");
+const detachedLeaseRefreshResource = new node_async_hooks_1.AsyncResource('zlink:owner-lease-tracker');
+class ZLinkOwnerLeaseTracker {
+    lane = new state_lane_1.ZLinkStateLane();
+    store;
+    options;
+    monotonicNowMs;
+    snapshots = new Map();
+    refreshes = new Map();
+    liveOwnerFingerprint;
+    liveOwnerVersion = 0;
+    constructor(options) {
+        this.store = options.store;
+        this.options = { ...Options_1.zlinkRuntimeDefaultLocationOptions, ...options.options };
+        this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+    }
+    async isOwnerLive(ownerId, signal) {
+        const snapshot = await this.getSnapshot(ownerId, signal);
+        return this.isLive(snapshot);
+    }
+    async remainingLeaseMs(ownerId, signal) {
+        const snapshot = await this.getSnapshot(ownerId, signal);
+        if (snapshot.result.kind !== 'found')
+            return 0;
+        return Math.max(0, snapshot.result.leaseExpiresAt.getTime()
+            - snapshot.result.storeNow.getTime()
+            - (this.monotonicNowMs() - snapshot.fetchedAtMs));
+    }
+    async remainingOwnerTokenLeaseMs(owner, signal) {
+        const snapshot = await this.getSnapshot(owner.ownerId, signal);
+        if (snapshot.result.kind !== 'found'
+            || snapshot.result.token.leaseGeneration !== owner.leaseGeneration)
+            return 0;
+        return Math.max(0, snapshot.result.leaseExpiresAt.getTime()
+            - snapshot.result.storeNow.getTime()
+            - (this.monotonicNowMs() - snapshot.fetchedAtMs));
+    }
+    async getLiveOwnerSetVersion(signal) {
+        const owners = await this.lane.run(() => [...this.snapshots.keys()]);
+        const refreshed = await Promise.all(owners.map(ownerId => this.getSnapshot(ownerId, signal)));
+        const live = refreshed
+            .filter(snapshot => this.isLive(snapshot))
+            .map(snapshot => snapshot.result.kind === 'found' ? snapshot.result.token.ownerId : '')
+            .filter(ownerId => ownerId.length > 0)
+            .sort()
+            .join('\n');
+        return await this.lane.run(() => {
+            if (live !== this.liveOwnerFingerprint) {
+                this.liveOwnerFingerprint = live;
+                this.liveOwnerVersion++;
+            }
+            return this.liveOwnerVersion;
+        });
+    }
+    async getSnapshot(ownerId, signal) {
+        const prepared = await this.lane.run(() => this.prepareSnapshotRefresh(ownerId));
+        if (prepared.snapshot !== undefined)
+            return prepared.snapshot;
+        if (prepared.start) {
+            void runDetachedLeaseRefresh(() => this.refreshSnapshot(ownerId, signal, prepared.refresh));
+        }
+        return await prepared.refresh.promise;
+    }
+    prepareSnapshotRefresh(ownerId) {
+        const current = this.snapshots.get(ownerId);
+        if (current !== undefined
+            && this.monotonicNowMs() - current.fetchedAtMs < this.options.pollingIntervalMs
+            && this.isLive(current)) {
+            return {
+                snapshot: current,
+                refresh: { promise: Promise.resolve(current), resolve: () => undefined, reject: () => undefined },
+                start: false
+            };
+        }
+        const activeRefresh = this.refreshes.get(ownerId);
+        if (activeRefresh !== undefined)
+            return { refresh: activeRefresh, start: false };
+        let resolve;
+        let reject;
+        const promise = new Promise((complete, fail) => {
+            resolve = complete;
+            reject = fail;
+        });
+        const refresh = { promise, resolve, reject };
+        this.refreshes.set(ownerId, refresh);
+        return { refresh, start: true };
+    }
+    async refreshSnapshot(ownerId, signal, refresh) {
+        try {
+            const snapshot = {
+                result: await this.store.readOwnerLease(ownerId, signal),
+                fetchedAtMs: this.monotonicNowMs()
+            };
+            await this.lane.run(() => this.completeSnapshotRefresh(ownerId, refresh, snapshot));
+        }
+        catch (error) {
+            await this.lane.run(() => this.failSnapshotRefresh(ownerId, refresh, error));
+        }
+    }
+    completeSnapshotRefresh(ownerId, refresh, snapshot) {
+        if (this.refreshes.get(ownerId) !== refresh)
+            return;
+        this.snapshots.set(ownerId, snapshot);
+        this.refreshes.delete(ownerId);
+        refresh.resolve(snapshot);
+    }
+    failSnapshotRefresh(ownerId, refresh, error) {
+        if (this.refreshes.get(ownerId) !== refresh)
+            return;
+        this.refreshes.delete(ownerId);
+        refresh.reject(error);
+    }
+    isLive(snapshot) {
+        if (snapshot.result.kind !== 'found')
+            return false;
+        const elapsedMs = this.monotonicNowMs() - snapshot.fetchedAtMs;
+        return snapshot.result.leaseExpiresAt.getTime()
+            - snapshot.result.storeNow.getTime()
+            - elapsedMs > 0;
+    }
+}
+exports.ZLinkOwnerLeaseTracker = ZLinkOwnerLeaseTracker;
+class ZLinkLiveRowFilter {
+    leaseTracker;
+    constructor(leaseTracker) {
+        this.leaseTracker = leaseTracker;
+    }
+    async filter(rows, ownerIdOf, signal, include) {
+        const live = [];
+        for (const row of rows) {
+            if ((include === undefined || include(row)) && await this.isLive(row, ownerIdOf, signal)) {
+                live.push(row);
+            }
+        }
+        return live;
+    }
+    async resolve(row, ownerIdOf, signal, include) {
+        if (row === undefined || (include !== undefined && !include(row))) {
+            return undefined;
+        }
+        return await this.isLive(row, ownerIdOf, signal) ? row : undefined;
+    }
+    async isLive(row, ownerIdOf, signal) {
+        return await this.leaseTracker.isOwnerLive(ownerIdOf(row), signal);
+    }
+}
+exports.ZLinkLiveRowFilter = ZLinkLiveRowFilter;
+function runDetachedLeaseRefresh(work) {
+    return detachedLeaseRefreshResource.runInAsyncScope(work);
+}

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

@@ -0,0 +1,19 @@
+import { type ZLinkActorLocation, type ZLinkActorLocationKey, ZLinkLocationKind, ZLinkLocationWriteIntent, type ZLinkLocationWriteResult, type ZLinkLocationWriteStatus, type ZLinkRouteLocation, type ZLinkRouteLocationKey, type ZLinkSpotLocation, type ZLinkSpotLocationKey } from './internal-location-contracts';
+import type { ZLinkLocationOwnerToken } from '../../contracts/Locations/Writes';
+export interface ZLinkOwnershipLostEvent {
+    readonly kind: ZLinkLocationKind;
+    readonly key: string;
+}
+export interface IZLinkLocationLifecycleRuntime {
+    readonly ownerId: string;
+    readonly currentOwnerToken?: ZLinkLocationOwnerToken;
+    reclaimOwnerAuthorities?(signal?: AbortSignal): Promise<void>;
+    addOwnershipLostHandler(handler: (event: ZLinkOwnershipLostEvent) => void): void;
+    removeOwnershipLostHandler(handler: (event: ZLinkOwnershipLostEvent) => void): void;
+    writeActor(actor: ZLinkActorLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    writeSpot(spot: ZLinkSpotLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    writeRoute(route: ZLinkRouteLocation, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+    removeActor(key: ZLinkActorLocationKey, generation: bigint, signal?: AbortSignal): Promise<ZLinkLocationWriteStatus>;
+    removeSpot(key: ZLinkSpotLocationKey, generation: bigint, signal?: AbortSignal): Promise<ZLinkLocationWriteStatus>;
+    removeRoute(key: ZLinkRouteLocationKey, generation: bigint, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;
+}

package/dist/runtime/locations/lifecycle-runtime.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,40 @@
+import type { ActorRef, RoutingId } from '../../contracts/Common';
+import type { ZLinkActorLocation, ZLinkLocationWriteStatus } from './internal-location-contracts';
+import type { ZLinkActorLocationStore, ZLinkSpotLocationStore } from './internal-store-contracts';
+import { ZLinkSpotKind } from '../../contracts/Spots';
+import { type ZLinkActorClaimActivation, type ZLinkActorClaimResult } from './actor-location-claims';
+export { ZLinkActorClaimStatus, type ZLinkActorClaimActivation, type ZLinkActorClaimResult } from './actor-location-claims';
+import type { ZLinkInstanceClosingAuthority, ZLinkTrackedInstanceAuthority } from './spot-location-claims';
+import type { ZLinkAuthorityStore } from './internal-store-contracts';
+import type { IZLinkLocationLifecycleRuntime } from './lifecycle-runtime';
+export type { IZLinkLocationLifecycleRuntime, ZLinkOwnershipLostEvent } from './lifecycle-runtime';
+export declare class ZLinkLocationLifecycle {
+    private readonly runtime;
+    private readonly actorClaims;
+    private readonly actorCleanupTasks;
+    private readonly spotClaims;
+    private readonly actorSessionRoutes;
+    private disposed;
+    private readonly ownershipLostHandler;
+    constructor(runtime: IZLinkLocationLifecycleRuntime, actorStore: ZLinkActorLocationStore, entryMeshName?: string, authorityStore?: ZLinkAuthorityStore, spotStore?: ZLinkSpotLocationStore, invalidateSpotRoute?: (spotId: RoutingId) => void);
+    dispose(): void;
+    executeActorClaimThenActivate<TActor>(actorType: string, actorId: string, nodeRid: RoutingId, deactivate: (() => Promise<void>) | undefined, activate: () => Promise<TActor>): Promise<ZLinkActorClaimActivation<TActor>>;
+    claimActor(actorType: string, actorId: string, nodeRid: RoutingId, deactivate?: () => Promise<void>): Promise<ZLinkActorClaimResult>;
+    setActorRef(actorType: string, actorId: string, actorRef: ActorRef, ownerNodeGeneration?: bigint): Promise<void>;
+    takeoverActorJoinedSpot(actorType: string, actorId: string, actorRef: ActorRef, spotMeshName: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, ownerNodeGeneration: bigint, deactivate?: () => Promise<void>): Promise<ZLinkActorClaimResult>;
+    notifyActorJoinedSpot(actorType: string, actorId: string, spotMeshName: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, ownerNodeGeneration: bigint): Promise<void>;
+    notifyActorLeftSpot(actorType: string, actorId: string, entrySpotId: RoutingId, entrySpotGeneration: bigint, membershipEpoch: bigint, ownerNodeGeneration: bigint): Promise<void>;
+    releaseActor(actorType: string, actorId: string, actorRef?: ActorRef): Promise<void>;
+    releaseActorEventually(actorType: string, actorId: string): Promise<void>;
+    ownsActor(actorType: string, actorId: string): boolean;
+    actorLocationSnapshot(actorId: string): ZLinkActorLocation | undefined;
+    private retryActorRelease;
+    claimSpot(meshName: string, spotId: RoutingId, spotType: string, nodeRid: RoutingId, spotKind: ZLinkSpotKind, spotGeneration: bigint, ownerNodeGeneration: bigint, deactivate?: () => Promise<void>): Promise<ZLinkLocationWriteStatus>;
+    releaseSpot(meshName: string, spotId: RoutingId, expectedObjectGeneration?: bigint): Promise<void>;
+    beginInstanceSpotClosing(meshName: string, spotId: RoutingId): Promise<ZLinkInstanceClosingAuthority | undefined>;
+    trackInstanceSpot(input: ZLinkTrackedInstanceAuthority): void;
+    reclaimOwnerRows(): Promise<void>;
+    bindActorSessionRoute(sessionRid: RoutingId, actorId: string, ownerNodeRid: RoutingId): Promise<void>;
+    removeActorSessionRoute(sessionRid: RoutingId): Promise<void>;
+    private onOwnershipLost;
+}