@zlink-systems/framework 0.10.0

package/src/contracts/Locations/Diagnostics.ts

@@ -0,0 +1,48 @@
+import type { RoutingId } from '../Common';
+
+export interface ZLinkLocationRuntimeStatus {
+  readonly storeHealthy: boolean;
+  readonly watchEnabled: boolean;
+  readonly pollingIntervalMs: number;
+  readonly lastRefreshAt?: Date;
+  readonly lastError?: string;
+  readonly ownerLeaseHealthy: boolean;
+  readonly ownerLeaseRenewedAt?: Date;
+}
+
+export enum ZLinkLocationTopologyState {
+  Discovered = 1,
+  Connecting = 2,
+  Ready = 3,
+  Lost = 4,
+  Error = 5,
+  Stopped = 6
+}
+
+export interface ZLinkLocationTopologyFilter {
+  readonly meshName?: string;
+  readonly nodeRid?: RoutingId;
+  readonly state?: ZLinkLocationTopologyState;
+}
+
+export interface ZLinkLocationTopologyEntry {
+  readonly meshName: string;
+  readonly nodeRid: RoutingId;
+  readonly endpoint: string;
+  readonly draining: boolean;
+  readonly state: ZLinkLocationTopologyState;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkLocationServiceSummaryFilter {
+  readonly meshName?: string;
+}
+
+export interface ZLinkLocationServiceSummary {
+  readonly meshName: string;
+  readonly totalCount: number;
+  readonly readyCount: number;
+  readonly errorCount: number;
+  readonly stoppedCount: number;
+  readonly lastUpdatedAt: Date;
+}

package/src/contracts/Locations/Keys.ts

@@ -0,0 +1,93 @@
+import type { RoutingId, SpotId } from '../Common';
+import type { ZLinkSpotKind } from '../Spots';
+import type { ZLinkLocationAutoConnectType, ZLinkLocationKind, ZLinkLocationRole, ZLinkRouteKind } from './Values';
+
+/**
+ * Peer identity is the full five-component tuple. Missing optional components
+ * are still part of the identity as "no value".
+ */
+export interface ZLinkPeerLocationKey {
+  readonly autoConnectType: ZLinkLocationAutoConnectType;
+  readonly meshName: string;
+  readonly role: ZLinkLocationRole;
+  readonly nodeRid?: RoutingId;
+  readonly endpoint?: string;
+}
+
+export interface ZLinkSpotLocationKey {
+  readonly meshName: string;
+  readonly spotId: SpotId;
+}
+
+export interface ZLinkMeshNodeDescriptorKey {
+  readonly meshName: string;
+  readonly rid: RoutingId;
+}
+
+export interface ZLinkClientServerServerDescriptorKey {
+  readonly channelName: string;
+  readonly serverRid: RoutingId;
+}
+
+export interface ZLinkFanoutPublisherDescriptorKey {
+  readonly channelName: string;
+  readonly publisherRid: RoutingId;
+}
+
+export interface ZLinkActorLocationKey {
+  readonly meshName: string;
+  readonly actorId: string;
+}
+
+export interface ZLinkRouteLocationKey {
+  readonly routeKind: ZLinkRouteKind;
+  readonly routeKey: string;
+}
+
+export type ZLinkLocationKey =
+  | { readonly kind: ZLinkLocationKind.Peer; readonly key: ZLinkPeerLocationKey }
+  | { readonly kind: ZLinkLocationKind.Spot; readonly key: ZLinkSpotLocationKey }
+  | { readonly kind: ZLinkLocationKind.Actor; readonly key: ZLinkActorLocationKey }
+  | { readonly kind: ZLinkLocationKind.Route; readonly key: ZLinkRouteLocationKey }
+  | {
+      readonly kind: ZLinkLocationKind.ClientServer;
+      readonly key: ZLinkClientServerServerDescriptorKey;
+    };
+
+export interface ZLinkPeerLocationFilter {
+  readonly autoConnectType?: ZLinkLocationAutoConnectType;
+  readonly meshName?: string;
+  readonly role?: ZLinkLocationRole;
+  readonly nodeRid?: RoutingId;
+  readonly endpoint?: string;
+}
+
+export interface ZLinkSpotLocationFilter {
+  readonly meshName?: string;
+  readonly spotType?: string;
+  readonly nodeRid?: RoutingId;
+  readonly spotKind?: ZLinkSpotKind;
+}
+
+export interface ZLinkActorLocationFilter {
+  readonly actorType?: string;
+  readonly nodeRid?: RoutingId;
+  readonly spotId?: SpotId;
+  readonly locationKind?: ZLinkSpotKind;
+}
+
+export interface ZLinkRouteLocationFilter {
+  readonly routeKind?: ZLinkRouteKind;
+  readonly ownerNodeRid?: RoutingId;
+  readonly ownerId?: string;
+}
+
+export interface ZLinkPageRequest {
+  readonly pageSize?: number;
+  readonly continuationToken?: string;
+}
+
+export interface ZLinkLocationPage<T> {
+  readonly items: readonly T[];
+  readonly continuationToken?: string;
+}

package/src/contracts/Locations/Models.ts

@@ -0,0 +1,7 @@
+export * from './Values';
+export * from './Rows';
+export * from './Keys';
+export * from './Writes';
+export * from './Watch';
+export * from './Diagnostics';
+export * from './RuntimeQuery';

package/src/contracts/Locations/Options.ts

@@ -0,0 +1,42 @@
+import type { ZLinkLocationOptionValues } from '../RouteMesh';
+
+export interface ZLinkLocationOptions {
+  ownerLeaseRenewIntervalMs(value: number): this;
+  ownerLeaseTtlMs(value: number): this;
+  pollingIntervalMs(value: number): this;
+  storeFailureGraceMs(value: number): this;
+  ownerLeaseFencingMarginMs(value: number): this;
+  ownerLeaseRenewTimeoutMs(value: number): this;
+  routeCacheMaxAgeMs(value: number): this;
+  messageFollowDurationMs(value: number): this;
+  sessionRelocationSealTimeoutMs(value: number): this;
+  relocationCutoverWaitTimeoutMs(value: number): this;
+  relocationPayloadChunkLimitBytes(value: number): this;
+  relocationInFlightPayloadBudgetBytes(value: number): this;
+  relocationNodeInFlightPayloadBudgetBytes(value: number): this;
+}
+
+export type ZLinkLocationOptionOverrides =
+  Partial<ZLinkLocationOptionValues> & { readonly listPageSize?: number };
+
+export const zlinkRuntimeDefaultLocationOptions: Readonly<
+  ZLinkLocationOptionValues & { readonly listPageSize: number }
+> = {
+  ownerLeaseRenewIntervalMs: 5000,
+  ownerLeaseTtlMs: 15000,
+  pollingIntervalMs: 1000,
+  listPageSize: 1000,
+  storeFailureGraceMs: 30000,
+  ownerLeaseFencingMarginMs: 5000,
+  ownerLeaseRenewTimeoutMs: 3000,
+  routeCacheMaxAgeMs: 15000,
+  messageFollowDurationMs: 30000,
+  sessionRelocationSealTimeoutMs: 3000,
+  relocationCutoverWaitTimeoutMs: 1000,
+  relocationPayloadChunkLimitBytes: 262144,
+  relocationInFlightPayloadBudgetBytes: 16777216,
+  relocationNodeInFlightPayloadBudgetBytes: 0
+};
+
+export const zlinkDefaultLocationOptions: Readonly<ZLinkLocationOptionValues> =
+  zlinkRuntimeDefaultLocationOptions;

package/src/contracts/Locations/Readiness.ts

@@ -0,0 +1,11 @@
+import type { RoutingId } from '../Common';
+import type { ZLinkLocationRole } from './Values';
+
+export interface ZLinkLocationReadiness {
+  isPeerReady(
+    meshName: string,
+    role: ZLinkLocationRole,
+    nodeRid?: RoutingId,
+    signal?: AbortSignal
+  ): Promise<boolean>;
+}

package/src/contracts/Locations/RelocationStore.ts

@@ -0,0 +1,51 @@
+declare const zlinkBlobReferenceBrand: unique symbol;
+
+export interface ZLinkBlobReference {
+  readonly value: string;
+  readonly [zlinkBlobReferenceBrand]: true;
+}
+
+export type ZLinkBlobPutResult =
+  | {
+      readonly kind: 'stored' | 'alreadyStored';
+      readonly expiresAt: Date;
+      readonly storeNow: Date;
+    }
+  | { readonly kind: 'conflict'; readonly storeNow: Date };
+
+export type ZLinkBlobReadResult =
+  | { readonly kind: 'missing'; readonly storeNow: Date }
+  | {
+      readonly kind: 'found';
+      readonly bytes: Uint8Array;
+      readonly expiresAt: Date;
+      readonly storeNow: Date;
+    };
+
+export type ZLinkBlobRenewResult =
+  | { readonly kind: 'missing'; readonly storeNow: Date }
+  | {
+      readonly kind: 'renewed';
+      readonly expiresAt: Date;
+      readonly storeNow: Date;
+    };
+
+export interface ZLinkRelocationStore {
+  put(
+    reference: ZLinkBlobReference,
+    payload: Uint8Array,
+    retentionMs: number,
+    signal?: AbortSignal
+  ): Promise<ZLinkBlobPutResult>;
+  read(
+    reference: ZLinkBlobReference,
+    signal?: AbortSignal
+  ): Promise<ZLinkBlobReadResult>;
+  renew(
+    reference: ZLinkBlobReference,
+    retentionMs: number,
+    signal?: AbortSignal
+  ): Promise<ZLinkBlobRenewResult>;
+  delete(reference: ZLinkBlobReference, signal?: AbortSignal): Promise<void>;
+  dispose?(): void | Promise<void>;
+}

package/src/contracts/Locations/Resolvers.ts

@@ -0,0 +1,8 @@
+import type {
+  ZLinkPeerLocation,
+  ZLinkPeerLocationFilter,
+} from './Models';
+
+export interface ZLinkPeerLocationResolver {
+  listLivePeers(filter: ZLinkPeerLocationFilter, signal?: AbortSignal): Promise<readonly ZLinkPeerLocation[]>;
+}

package/src/contracts/Locations/Rows.ts

@@ -0,0 +1,164 @@
+import type { ActorRef, RoutingId, SpotId } from '../Common';
+import type { ZLinkSpotKind } from '../Spots';
+import type { ZLinkLocationAutoConnectType, ZLinkLocationRole, ZLinkRouteKind } from './Values';
+
+export enum ZLinkObjectRole {
+  None = 'none',
+  Client = 'client',
+  Server = 'server'
+}
+
+export enum ZLinkFrameworkRuntimeState {
+  Preparing = 0,
+  Serving = 1,
+  Relocating = 2,
+  Relocated = 3,
+  Draining = 4,
+  Stopped = 5,
+  Error = 6
+}
+export type ZLinkObjectMaintenancePolicyKind = 'disabled' | 'recreate' | 'snapshot';
+
+export interface ZLinkObjectCapability {
+  readonly objectKind: 'actor' | 'user_spot' | 'instance_spot';
+  readonly stableType: string;
+  readonly policy: ZLinkObjectMaintenancePolicyKind;
+  readonly hasSnapshotAdapter: boolean;
+  readonly limit: number;
+}
+
+export interface ZLinkPopulationCapacity {
+  readonly active: number;
+  readonly reserved: number;
+  readonly limit: number;
+}
+
+export interface ZLinkSpotTypeCapacity extends ZLinkPopulationCapacity {
+  readonly objectKind: 'user_spot' | 'instance_spot';
+  readonly stableType: string;
+}
+
+export interface ZLinkPeerLocation {
+  readonly autoConnectType: ZLinkLocationAutoConnectType;
+  readonly meshName: string;
+  readonly nodeRid?: RoutingId;
+  readonly role: ZLinkLocationRole;
+  readonly endpoint: string;
+  readonly weight: number;
+  readonly draining: boolean;
+  readonly value: bigint;
+  readonly metadata?: Readonly<Record<string, string>>;
+  readonly capabilities?: readonly string[];
+  readonly ownerId: string;
+  readonly generation: bigint;
+  readonly updatedAt: Date;
+}
+
+/** RouteMesh discovery descriptor fixed by the 10.0 location-store contract. */
+export interface ZLinkMeshNodeDescriptor {
+  readonly meshName: string;
+  readonly rid: RoutingId;
+  readonly lifecycleGeneration: bigint;
+  readonly descriptorRevision: bigint;
+  readonly endpoint: string;
+  readonly objectRole: ZLinkObjectRole;
+  readonly entrySpotId?: string;
+  readonly placementWeight: number;
+  readonly populationCapacity: {
+    readonly actors: ZLinkPopulationCapacity;
+    readonly spots: ZLinkPopulationCapacity;
+    readonly spotTypes: readonly ZLinkSpotTypeCapacity[];
+  };
+  readonly activationConcurrency: {
+    readonly active: number;
+    readonly limit: number;
+  };
+  readonly channelWeights: Readonly<Record<string, number>>;
+  readonly applicationVersion: bigint;
+  readonly spotTypes: readonly string[];
+  readonly objectCapabilities: readonly ZLinkObjectCapability[];
+  readonly maintenanceWave?: string;
+  readonly state: ZLinkFrameworkRuntimeState;
+  readonly securityIdentity: string;
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkClientServerServerDescriptor {
+  readonly channelName: string;
+  readonly serverRid: RoutingId;
+  readonly lifecycleGeneration: bigint;
+  readonly descriptorRevision: bigint;
+  readonly endpoint: string;
+  readonly weight: number;
+  readonly state: ZLinkFrameworkRuntimeState;
+  readonly securityIdentity: string;
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkFanoutPublisherDescriptor {
+  readonly channelName: string;
+  readonly publisherRid: RoutingId;
+  readonly lifecycleGeneration: bigint;
+  readonly descriptorRevision: bigint;
+  readonly endpoint: string;
+  readonly state: ZLinkFrameworkRuntimeState;
+  readonly securityIdentity: string;
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkSpotLocation {
+  readonly meshName: string;
+  readonly spotId: SpotId;
+  /** Core lifecycle generation of the addressed Spot. */
+  readonly spotGeneration: bigint;
+  readonly spotType: string;
+  /** MeshNode that currently owns this Spot. */
+  readonly ownerNodeRid: RoutingId;
+  /** Core lifecycle generation of the owning MeshNode. */
+  readonly ownerNodeGeneration: bigint;
+  readonly spotKind: ZLinkSpotKind;
+  readonly ownerId: string;
+  /** Generation of the exact owner lease that published this row. */
+  readonly leaseGeneration: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkActorLocation {
+  /** RouteMesh that owns this Actor location. */
+  readonly meshName: string;
+  readonly actorId: string;
+  readonly actorType: string;
+  readonly actorRef: ActorRef;
+  /** MeshNode that currently owns this Actor. */
+  readonly ownerNodeRid: RoutingId;
+  readonly ownerNodeGeneration: bigint;
+  /** Kind of Spot that currently owns this Actor. */
+  readonly spotKind: ZLinkSpotKind;
+  readonly spotId: SpotId;
+  readonly spotGeneration: bigint;
+  readonly membershipEpoch: bigint;
+  readonly ownerId: string;
+  /** Generation of the exact owner lease that published this row. */
+  readonly leaseGeneration: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkRouteLocation {
+  readonly routeKind: ZLinkRouteKind;
+  readonly routeKey: string;
+  readonly ownerNodeRid: RoutingId;
+  readonly ownerId: string;
+  readonly generation: bigint;
+  /**
+   * Framework internal route payload. This is not an application key-value
+   * storage surface.
+   */
+  readonly value: Uint8Array;
+  readonly updatedAt: Date;
+}

package/src/contracts/Locations/RuntimeQuery.ts

@@ -0,0 +1,56 @@
+import type {
+  ZLinkLocationPage,
+  ZLinkLocationRuntimeStatus,
+  ZLinkLocationServiceSummary,
+  ZLinkLocationServiceSummaryFilter,
+  ZLinkLocationTopologyEntry,
+  ZLinkLocationTopologyFilter,
+  ZLinkMeshNodeDescriptor,
+  ZLinkPageRequest,
+} from './Models';
+import type { ZLinkPlacementObjectKind } from './Authority';
+
+export type ZLinkLocationObjectState = 'creating' | 'ready' | 'unavailable';
+
+export interface ZLinkLocationObjectEntry {
+  readonly globalId: string;
+  readonly objectGeneration: bigint;
+  readonly meshName: string;
+  readonly nodeRid: import('../Common').RoutingId;
+  readonly state: ZLinkLocationObjectState;
+  readonly stableType: string;
+}
+
+export interface ZLinkLocationObjectFilter {
+  readonly objectKind: ZLinkPlacementObjectKind;
+  readonly stableType?: string;
+  readonly meshName?: string;
+}
+
+export interface ZLinkLocationRuntimeQuery {
+  getStatus(signal?: AbortSignal): Promise<ZLinkLocationRuntimeStatus>;
+  listMeshNodeDescriptors(
+    meshName: string,
+    page?: ZLinkPageRequest,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationPage<ZLinkMeshNodeDescriptor>>;
+  listTopology(
+    filter: ZLinkLocationTopologyFilter,
+    page?: ZLinkPageRequest,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationPage<ZLinkLocationTopologyEntry>>;
+  listServiceSummaries(
+    filter: ZLinkLocationServiceSummaryFilter,
+    page?: ZLinkPageRequest,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationPage<ZLinkLocationServiceSummary>>;
+  findActorLocation(
+    actorId: import('../Common').ActorId,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationObjectEntry | undefined>;
+  findSpotLocation(
+    spotId: import('../Common').SpotId,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationObjectEntry | undefined>;
+  listObjectLocations(filter: ZLinkLocationObjectFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkLocationObjectEntry>>;
+}

package/src/contracts/Locations/Stores.ts

@@ -0,0 +1,92 @@
+declare const zlinkStoreKeyBrand: unique symbol;
+declare const zlinkStoreVersionBrand: unique symbol;
+declare const zlinkStoreScanCursorBrand: unique symbol;
+
+export interface ZLinkStoreKey {
+  readonly value: string;
+  readonly [zlinkStoreKeyBrand]: true;
+}
+
+export interface ZLinkStoreVersion {
+  readonly value: string;
+  readonly [zlinkStoreVersionBrand]: true;
+}
+
+export interface ZLinkStoreScanCursor {
+  readonly value: string;
+  readonly [zlinkStoreScanCursorBrand]: true;
+}
+
+export interface ZLinkStoreValue {
+  readonly bytes: Uint8Array;
+  readonly version: ZLinkStoreVersion;
+  readonly expiresAt?: Date;
+  readonly storeNow: Date;
+}
+
+export type ZLinkStoreReadResult =
+  | { readonly kind: 'missing'; readonly storeNow: Date }
+  | { readonly kind: 'found'; readonly value: ZLinkStoreValue };
+
+export type ZLinkStoreCondition =
+  | { readonly kind: 'missing'; readonly key: ZLinkStoreKey }
+  | {
+      readonly kind: 'version';
+      readonly key: ZLinkStoreKey;
+      readonly expected: ZLinkStoreVersion;
+    };
+
+export type ZLinkStoreMutation =
+  | {
+      readonly kind: 'put';
+      readonly key: ZLinkStoreKey;
+      readonly bytes: Uint8Array;
+      readonly retentionMs?: number;
+    }
+  | { readonly kind: 'delete'; readonly key: ZLinkStoreKey };
+
+export interface ZLinkStoreWriteRequest {
+  readonly conditions: readonly ZLinkStoreCondition[];
+  readonly mutations: readonly ZLinkStoreMutation[];
+}
+
+export interface ZLinkStorePutVersion {
+  readonly key: ZLinkStoreKey;
+  readonly version: ZLinkStoreVersion;
+}
+
+export type ZLinkStoreWriteResult =
+  | {
+      readonly kind: 'applied';
+      readonly putVersions: readonly ZLinkStorePutVersion[];
+      readonly storeNow: Date;
+    }
+  | { readonly kind: 'conflict'; readonly storeNow: Date };
+
+export interface ZLinkStoreScanRequest {
+  readonly prefix: string;
+  readonly cursor?: ZLinkStoreScanCursor;
+  readonly limit: number;
+}
+
+export interface ZLinkStoreScanItem {
+  readonly key: ZLinkStoreKey;
+  readonly value: ZLinkStoreValue;
+}
+
+export interface ZLinkStoreScanPage {
+  readonly items: readonly ZLinkStoreScanItem[];
+  readonly nextCursor?: ZLinkStoreScanCursor;
+  readonly storeNow: Date;
+}
+
+export type ZLinkStoreScanResult =
+  | { readonly kind: 'page'; readonly value: ZLinkStoreScanPage }
+  | { readonly kind: 'expired' };
+
+export interface ZLinkLocationStore {
+  read(key: ZLinkStoreKey, signal?: AbortSignal): Promise<ZLinkStoreReadResult>;
+  write(request: ZLinkStoreWriteRequest, signal?: AbortSignal): Promise<ZLinkStoreWriteResult>;
+  scan(request: ZLinkStoreScanRequest, signal?: AbortSignal): Promise<ZLinkStoreScanResult>;
+  dispose?(): void | Promise<void>;
+}

package/src/contracts/Locations/Values.ts

@@ -0,0 +1,32 @@
+export enum ZLinkLocationAutoConnectType {
+  Invalid = 0,
+  RouteMesh = 1,
+  Fanout = 2
+}
+
+export enum ZLinkLocationRole {
+  Invalid = 0,
+  // Value 1 is reserved for the removed gateway role. The numeric values are
+  // serialized on the wire and in Redis row JSON, so they must not change.
+  Spot = 2,
+  Router = 3,
+  Dealer = 4,
+  Pub = 5,
+  Sub = 6
+}
+
+export enum ZLinkRouteKind {
+  Invalid = 0,
+  ActorSession = 1,
+  SpotName = 2,
+  FrameworkRoute = 3
+}
+
+export enum ZLinkLocationKind {
+  Invalid = 0,
+  Peer = 1,
+  Spot = 2,
+  Actor = 3,
+  Route = 4,
+  ClientServer = 5
+}

package/src/contracts/Locations/Watch.ts

@@ -0,0 +1,16 @@
+import type { ZLinkLocationKind } from './Values';
+
+export enum ZLinkLocationChangeScopeKind {
+  MeshNode = 'meshNode',
+  ClientServer = 'clientServer',
+  Spot = 'spot',
+  Authority = 'authority',
+  OwnerLease = 'ownerLease',
+  FanoutPublisher = 'fanoutPublisher'
+}
+
+export interface ZLinkLocationChangeStampScope {
+  readonly kind: ZLinkLocationKind | ZLinkLocationChangeScopeKind;
+  readonly meshName?: string;
+  readonly channelName?: string;
+}

package/src/contracts/Locations/Writes.ts

@@ -0,0 +1,56 @@
+export enum ZLinkLocationWriteIntent {
+  NewClaim = 1,
+  Renew = 2,
+  Takeover = 3
+}
+
+export enum ZLinkLocationWriteStatus {
+  Stored = 'stored',
+  IgnoredStale = 'ignoredStale',
+  RejectedConflict = 'rejectedConflict'
+}
+
+export interface ZLinkLocationWriteResult {
+  readonly status: ZLinkLocationWriteStatus;
+  readonly generation: bigint;
+  readonly updatedAt: Date;
+}
+
+export interface ZLinkLocationOwnerToken {
+  readonly ownerId: string;
+  readonly leaseGeneration: bigint;
+}
+
+export type ZLinkOwnerLeaseClaimResult =
+  | {
+      readonly kind: 'claimed';
+      readonly token: ZLinkLocationOwnerToken;
+      readonly leaseExpiresAt: Date;
+      readonly storeNow: Date;
+    }
+  | { readonly kind: 'conflict' }
+  | { readonly kind: 'generationExhausted' };
+
+export type ZLinkOwnerLeaseRenewResult =
+  | {
+      readonly kind: 'renewed';
+      readonly leaseExpiresAt: Date;
+      readonly storeNow: Date;
+    }
+  | { readonly kind: 'stale' };
+
+export type ZLinkOwnerLeaseReleaseResult = 'released' | 'stale';
+
+export type ZLinkOwnerLeaseReadResult =
+  | {
+      readonly kind: 'found';
+      readonly token: ZLinkLocationOwnerToken;
+      readonly leaseExpiresAt: Date;
+      readonly storeNow: Date;
+    }
+  | { readonly kind: 'missing' };
+
+export type ZLinkOwnerLeaseRenewed = Extract<
+  ZLinkOwnerLeaseRenewResult,
+  { readonly kind: 'renewed' }
+>;