@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,213 @@
+import type {
+  ZLinkLocationStore,
+  ZLinkStoreKey,
+  ZLinkStoreReadResult,
+  ZLinkStoreScanCursor,
+  ZLinkStoreScanRequest,
+  ZLinkStoreScanResult,
+  ZLinkStoreVersion,
+  ZLinkStoreWriteRequest,
+  ZLinkStoreWriteResult
+} from '../../contracts';
+
+interface StoredValue {
+  readonly bytes: Uint8Array;
+  readonly version: ZLinkStoreVersion;
+  readonly expiresAt?: Date;
+}
+
+interface ScanSnapshot {
+  readonly items: readonly { readonly key: ZLinkStoreKey; readonly value: StoredValue }[];
+}
+
+/**
+ * Framework-owned primitive Store used by the explicit in-memory option.
+ * Domain records are encoded by ZLinkLocationStoreRepository.
+ */
+export class ZLinkInMemoryProviderLocationStore implements ZLinkLocationStore {
+  private readonly values = new Map<string, StoredValue>();
+  private readonly scans = new Map<string, ScanSnapshot>();
+  private nextVersion = 0n;
+  private nextScan = 0n;
+
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  async read(key: ZLinkStoreKey, signal?: AbortSignal): Promise<ZLinkStoreReadResult> {
+    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: ZLinkStoreWriteRequest,
+    signal?: AbortSignal
+  ): Promise<ZLinkStoreWriteResult> {
+    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: ZLinkStoreScanRequest,
+    signal?: AbortSignal
+  ): Promise<ZLinkStoreScanResult> {
+    signal?.throwIfAborted();
+    requireScanRequest(request);
+    const storeNow = this.now();
+    let snapshotId: string;
+    let offset: number;
+    let snapshot: ScanSnapshot | undefined;
+    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
+      }
+    };
+  }
+
+  private liveValue(key: string, storeNow: Date): StoredValue | undefined {
+    const value = this.values.get(key);
+    if (value?.expiresAt !== undefined && value.expiresAt.getTime() <= storeNow.getTime()) {
+      this.values.delete(key);
+      return undefined;
+    }
+    return value;
+  }
+}
+
+export function storeKey(value: string): ZLinkStoreKey {
+  return { value } as ZLinkStoreKey;
+}
+
+export function storeVersion(value: string): ZLinkStoreVersion {
+  return { value } as ZLinkStoreVersion;
+}
+
+function scanCursor(value: string): ZLinkStoreScanCursor {
+  return { value } as ZLinkStoreScanCursor;
+}
+
+function parseCursor(cursor: ZLinkStoreScanCursor): [string, number] {
+  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: ZLinkStoreWriteRequest): void {
+  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: ZLinkStoreScanRequest): void {
+  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: Uint8Array, retentionMs: number | undefined): void {
+  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: string): void {
+  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/src/runtime/locations/index.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/src/runtime/locations/internal-location-contracts.ts

@@ -0,0 +1,22 @@
+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/src/runtime/locations/internal-store-contracts.ts

@@ -0,0 +1,90 @@
+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/src/runtime/locations/key-codec.ts

@@ -0,0 +1,61 @@
+import type { RoutingId } from '../../contracts/Common';
+import {
+  type ZLinkActorLocationKey,
+  type ZLinkPeerLocationKey,
+  type ZLinkRouteLocationKey,
+  type ZLinkSpotLocationKey
+} from './internal-location-contracts';
+import { zlinkLocationAutoConnectTypeName, zlinkLocationRoleName } from './canonical-codec';
+import { encodeRoutingIdStorageHex } from '../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.
+export const ZLinkLocationKeyCodec = Object.freeze({
+  encodePeerKey(key: ZLinkPeerLocationKey): string {
+    const identity = key.nodeRid === undefined ? key.endpoint ?? '' : encodeRoutingIdHex(key.nodeRid);
+    return encodeSegments(
+      zlinkLocationAutoConnectTypeName(key.autoConnectType),
+      key.meshName,
+      zlinkLocationRoleName(key.role),
+      identity
+    );
+  },
+
+  encodeSpotKey(key: ZLinkSpotLocationKey): string {
+    return encodeSegments(key.meshName, requireSpotId(key.spotId));
+  },
+
+  encodeActorKey(key: ZLinkActorLocationKey): string {
+    return encodeSegments(key.meshName, key.actorId);
+  },
+
+  encodeRouteKey(key: ZLinkRouteLocationKey): string {
+    return encodeSegments(String(key.routeKind), key.routeKey);
+  },
+
+  encodeRoutingIdHex,
+  normalizeActorType
+});
+
+function normalizeActorType(actorType: string | undefined): string {
+  return actorType ?? '';
+}
+
+function encodeSegments(...segments: readonly string[]): string {
+  return segments.map(
+    (segment) => `${Buffer.byteLength(segment, 'utf8')}:${segment}`
+  ).join('');
+}
+
+function requireSpotId(value: string): string {
+  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: RoutingId): string {
+  return encodeRoutingIdStorageHex(routingId);
+}

package/src/runtime/locations/lease-tracker.ts

@@ -0,0 +1,221 @@
+import {
+  zlinkRuntimeDefaultLocationOptions,
+  type ZLinkLocationOptionOverrides
+} from '../../contracts/Locations/Options';
+import {
+  type ZLinkLocationOwnerToken,
+  type ZLinkOwnerLeaseReadResult
+} from './internal-location-contracts';
+import type { ZLinkOwnerLeaseStore } from './internal-store-contracts';
+import { AsyncResource } from 'node:async_hooks';
+import { ZLinkStateLane } from '../execution/state-lane';
+
+const detachedLeaseRefreshResource = new AsyncResource('zlink:owner-lease-tracker');
+
+export interface ZLinkOwnerLeaseTrackerOptions {
+  readonly store: ZLinkOwnerLeaseStore;
+  readonly options?: ZLinkLocationOptionOverrides;
+  readonly monotonicNowMs?: () => number;
+}
+
+interface OwnerLeaseTrackerSnapshot {
+  readonly result: ZLinkOwnerLeaseReadResult;
+  readonly fetchedAtMs: number;
+}
+
+interface OwnerLeaseRefresh {
+  readonly promise: Promise<OwnerLeaseTrackerSnapshot>;
+  readonly resolve: (snapshot: OwnerLeaseTrackerSnapshot) => void;
+  readonly reject: (error: unknown) => void;
+}
+
+export class ZLinkOwnerLeaseTracker {
+  private readonly lane = new ZLinkStateLane();
+  private readonly store: ZLinkOwnerLeaseStore;
+  private readonly options: Required<ZLinkLocationOptionOverrides>;
+  private readonly monotonicNowMs: () => number;
+  private readonly snapshots = new Map<string, OwnerLeaseTrackerSnapshot>();
+  private readonly refreshes = new Map<string, OwnerLeaseRefresh>();
+  private liveOwnerFingerprint?: string;
+  private liveOwnerVersion = 0;
+
+  constructor(options: ZLinkOwnerLeaseTrackerOptions) {
+    this.store = options.store;
+    this.options = { ...zlinkRuntimeDefaultLocationOptions, ...options.options };
+    this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
+  }
+
+  async isOwnerLive(ownerId: string, signal?: AbortSignal): Promise<boolean> {
+    const snapshot = await this.getSnapshot(ownerId, signal);
+    return this.isLive(snapshot);
+  }
+
+  async remainingLeaseMs(ownerId: string, signal?: AbortSignal): Promise<number> {
+    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: ZLinkLocationOwnerToken,
+    signal?: AbortSignal
+  ): Promise<number> {
+    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?: AbortSignal): Promise<number> {
+    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;
+    });
+  }
+
+  private async getSnapshot(
+    ownerId: string,
+    signal?: AbortSignal
+  ): Promise<OwnerLeaseTrackerSnapshot> {
+    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;
+  }
+
+  private prepareSnapshotRefresh(ownerId: string): {
+    readonly snapshot?: OwnerLeaseTrackerSnapshot;
+    readonly refresh: OwnerLeaseRefresh;
+    readonly start: boolean;
+  } {
+    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!: (snapshot: OwnerLeaseTrackerSnapshot) => void;
+    let reject!: (error: unknown) => void;
+    const promise = new Promise<OwnerLeaseTrackerSnapshot>((complete, fail) => {
+      resolve = complete;
+      reject = fail;
+    });
+    const refresh = { promise, resolve, reject };
+    this.refreshes.set(ownerId, refresh);
+    return { refresh, start: true };
+  }
+
+  private async refreshSnapshot(
+    ownerId: string,
+    signal: AbortSignal | undefined,
+    refresh: OwnerLeaseRefresh
+  ): Promise<void> {
+    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));
+    }
+  }
+
+  private completeSnapshotRefresh(
+    ownerId: string,
+    refresh: OwnerLeaseRefresh,
+    snapshot: OwnerLeaseTrackerSnapshot
+  ): void {
+    if (this.refreshes.get(ownerId) !== refresh) return;
+    this.snapshots.set(ownerId, snapshot);
+    this.refreshes.delete(ownerId);
+    refresh.resolve(snapshot);
+  }
+
+  private failSnapshotRefresh(
+    ownerId: string,
+    refresh: OwnerLeaseRefresh,
+    error: unknown
+  ): void {
+    if (this.refreshes.get(ownerId) !== refresh) return;
+    this.refreshes.delete(ownerId);
+    refresh.reject(error);
+  }
+
+  private isLive(snapshot: OwnerLeaseTrackerSnapshot): boolean {
+    if (snapshot.result.kind !== 'found') return false;
+    const elapsedMs = this.monotonicNowMs() - snapshot.fetchedAtMs;
+    return snapshot.result.leaseExpiresAt.getTime()
+      - snapshot.result.storeNow.getTime()
+      - elapsedMs > 0;
+  }
+}
+
+export class ZLinkLiveRowFilter {
+  constructor(private readonly leaseTracker: ZLinkOwnerLeaseTracker) {}
+
+  async filter<TRow>(
+    rows: readonly TRow[],
+    ownerIdOf: (row: TRow) => string,
+    signal?: AbortSignal,
+    include?: (row: TRow) => boolean
+  ): Promise<TRow[]> {
+    const live: TRow[] = [];
+    for (const row of rows) {
+      if ((include === undefined || include(row)) && await this.isLive(row, ownerIdOf, signal)) {
+        live.push(row);
+      }
+    }
+    return live;
+  }
+
+  async resolve<TRow>(
+    row: TRow | undefined,
+    ownerIdOf: (row: TRow) => string,
+    signal?: AbortSignal,
+    include?: (row: TRow) => boolean
+  ): Promise<TRow | undefined> {
+    if (row === undefined || (include !== undefined && !include(row))) {
+      return undefined;
+    }
+    return await this.isLive(row, ownerIdOf, signal) ? row : undefined;
+  }
+
+  private async isLive<TRow>(
+    row: TRow,
+    ownerIdOf: (row: TRow) => string,
+    signal?: AbortSignal
+  ): Promise<boolean> {
+    return await this.leaseTracker.isOwnerLive(ownerIdOf(row), signal);
+  }
+}
+
+function runDetachedLeaseRefresh(work: () => Promise<void>): Promise<void> {
+  return detachedLeaseRefreshResource.runInAsyncScope(work);
+}

package/src/runtime/locations/lifecycle-runtime.ts

@@ -0,0 +1,44 @@
+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>;
+}