@zlink-systems/framework 0.19.0 → 0.21.0

package/src/runtime/locations/location-store-repository.ts

@@ -1,4 +1,4 @@
-import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import type {
   ZLinkLocationStore,
   ZLinkLocationPage,
@@ -74,6 +74,11 @@ import {
 import { ZLinkLocationWriteStatus as WriteStatus } from '../../contracts/Locations';
 import { ZLinkInMemoryLocationStore } from './in-memory-location-store';
 import { storeKey } from './in-memory-provider-location-store';
+import {
+  creationTerminalPreimage,
+  opaqueRecordPreimage,
+  routingIdHexSegment
+} from './opaque-record-key';
 import { decodeAuthorityKey, encodeAuthorityKey } from './authority-key-codec';
 import { ZLinkAggregateInventoryStore } from './aggregate-inventory-store';
 import type { RoutingId } from '../../contracts/Common/CoreTypes';
@@ -101,7 +106,6 @@ type StoredAuthoritySnapshot = Omit<
 
 interface AuthorityRecord {
   readonly snapshot: StoredAuthoritySnapshot;
-  readonly reservationId?: string;
   readonly terminal?: 'committed' | 'rejected' | 'failed' | 'aborted';
   readonly aggregate?: AggregateParticipantFenceRecord;
   readonly visibleStoreVersion?: string;
@@ -1174,7 +1178,6 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         capacity: cloneCapacity(request.capacity)
       };
       const record: AuthorityRecord = {
-        reservationId,
         snapshot: {
           payload: Buffer.from(request.creatingPayload),
           objectGeneration: generation,
@@ -1246,7 +1249,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       const record = decodeAuthorityRecord(current.value.bytes);
       if (
         record.terminal === 'committed'
-        && record.reservationId === request.reservationId
+        && record.snapshot.pendingCreation === undefined
         && record.snapshot.allocation.state === 'active'
       ) {
         return {
@@ -1255,7 +1258,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         };
       }
       if (
-        record.reservationId !== request.reservationId
+        record.snapshot.pendingCreation?.reservationId !== request.reservationId
         || current.value.version.value !== request.expectedStoreVersion
         || record.snapshot.allocation.state !== 'reserved'
         || !sameCreationTarget(record.snapshot, request.target)
@@ -1277,7 +1280,6 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         ? emptyCapacityRecord()
         : decodeJson<CapacityRecord>(capacityRead.value.bytes);
       const ready: AuthorityRecord = {
-        reservationId: request.reservationId,
         terminal: 'committed',
         snapshot: {
           ...record.snapshot,
@@ -1328,7 +1330,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       if (current.kind === 'missing') return { kind: 'stale' };
       const record = decodeAuthorityRecord(current.value.bytes);
       if (
-        record.reservationId !== request.reservationId
+        record.snapshot.pendingCreation?.reservationId !== request.reservationId
         || current.value.version.value !== request.expectedStoreVersion
         || record.snapshot.allocation.state !== 'reserved'
         || !sameCreationTarget(record.snapshot, request.target)
@@ -1404,15 +1406,18 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       if (existingTerminal.kind === 'found') {
         return {
           kind: 'alreadyCompleted',
-          terminal: reviveCreationTerminal(
-            decodeJson<ZLinkCreationTerminalRecord>(existingTerminal.value.bytes)
+          terminal: retainedCreationTerminal(
+            terminal.operation,
+            existingTerminal.value.bytes,
+            existingTerminal.value.expiresAt,
+            existingTerminal.value.storeNow
           )
         };
       }
       if (current.kind === 'missing') return { kind: 'stale' };
       const record = decodeAuthorityRecord(current.value.bytes);
       if (
-        record.reservationId !== request.reservationId
+        record.snapshot.pendingCreation?.reservationId !== request.reservationId
         || current.value.version.value !== request.expectedStoreVersion
         || record.snapshot.allocation.state !== 'reserved'
         || !sameCreationTarget(record.snapshot, request.target)
@@ -1450,7 +1455,6 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
               kind: 'put' as const,
               key: rowKey,
               bytes: encodeAuthorityRecord({
-                reservationId: request.reservationId,
                 terminal: 'committed',
                 snapshot: {
                   ...record.snapshot,
@@ -1493,7 +1497,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
           {
             kind: 'put',
             key: terminalRowKey,
-            bytes: encodeJson(terminalAtStore),
+            bytes: terminalAtStore.terminalEnvelope,
             retentionMs
           }
         ]
@@ -1513,7 +1517,6 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       }
       const readyRecord = decodeAuthorityRecord(
         encodeAuthorityRecord({
-          reservationId: request.reservationId,
           terminal: 'committed',
           snapshot: {
             ...record.snapshot,
@@ -1541,9 +1544,7 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       ? { kind: 'missing', storeNow: result.storeNow }
       : {
           kind: 'found',
-          record: reviveCreationTerminal(
-            decodeJson<ZLinkCreationTerminalRecord>(result.value.bytes)
-          )
+          terminalEnvelope: Buffer.from(result.value.bytes)
         };
   }
 
@@ -2152,10 +2153,11 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         if (result.kind === 'deleted') removed += 1n;
         continue;
       }
-      if (record.reservationId === undefined) continue;
+      const reservationId = record.snapshot.pendingCreation?.reservationId;
+      if (reservationId === undefined) continue;
       const aborted = await this.abort({
         key: identity,
-        reservationId: record.reservationId,
+        reservationId,
         expectedStoreVersion: current.value.version.value,
         target: {
           meshName: record.snapshot.allocation.descriptor.meshName,
@@ -3141,13 +3143,13 @@ function sha256Hex(bytes: Uint8Array): string {
 // literal NUL bytes -- the same scheme the opaque record store hashes with
 // SHA-256 to derive the Redis key -- so a runtime in one language can read a
 // record another language wrote. Not used for framework-internal-only rows
-// (aggregate/capacity/creation-terminal/spot/actor/route), which stay on the
-// legacy PREFIX scheme since they aren't part of the public opaque contract.
+// (aggregate/capacity/spot/actor/route), which stay on the legacy PREFIX
+// scheme since they aren't part of the public opaque contract.
 function ownerKey(ownerId: string) {
-  return storeKey(`owner-lease\0${requireNoNul(ownerId, 'OwnerId')}`);
+  return storeKey(opaqueRecordPreimage('owner-lease', requireNoNul(ownerId, 'OwnerId')));
 }
 
-const AUTHORITY_PREIMAGE_PREFIX = 'authority\0';
+const AUTHORITY_PREIMAGE_PREFIX = `${opaqueRecordPreimage('authority')}\0`;
 
 function authorityKey(value: string) {
   return storeKey(authorityPreimage(value));
@@ -3158,7 +3160,11 @@ function authorityPreimage(value: string): string {
   // §2.3: Entry|User|Instance Spot kinds share one segment ("spot") -- one
   // Id has exactly one authority row regardless of spot kind.
   const segment = decoded.kind === 'actor' ? 'actor' : 'spot';
-  return `${AUTHORITY_PREIMAGE_PREFIX}${segment}\0${requireNoNul(decoded.globalId, 'Authority Id')}`;
+  return opaqueRecordPreimage(
+    'authority',
+    segment,
+    requireNoNul(decoded.globalId, 'Authority Id')
+  );
 }
 
 // Reverses authorityPreimage(): recovers the framework-internal zla1-encoded
@@ -3235,42 +3241,49 @@ function capacityKey(meshName: string, nodeRid: string) {
 
 function creationTerminalKey(operation: ZLinkCreationOperationIdentity) {
   validateCreationOperation(operation);
-  return storeKey(`${PREFIX}creation-terminal:${[
-    String(operation.sourceNodeRid),
-    operation.sourceNodeGeneration.toString(),
-    operation.operationId.high.toString(16).padStart(16, '0'),
-    operation.operationId.low.toString(16).padStart(16, '0')
-  ].map(encodeURIComponent).join(':')}`);
+  return storeKey(creationTerminalPreimage(operation));
 }
 
 function meshPrefix(meshName: string): string {
-  return `mesh-node\0${requireNoNul(meshName, 'MeshName')}\0`;
+  return `${opaqueRecordPreimage('mesh-node', requireNoNul(meshName, 'MeshName'))}\0`;
 }
 
 function meshKey(meshName: string, nodeRid: RoutingId) {
-  return storeKey(`${meshPrefix(meshName)}${routingIdHexSegment(nodeRid)}`);
+  return storeKey(opaqueRecordPreimage(
+    'mesh-node',
+    requireNoNul(meshName, 'MeshName'),
+    routingIdHexSegment(nodeRid)
+  ));
 }
 
 function clientServerPrefix(channelName: string): string {
-  return `client-server\0${requireNoNul(channelName, 'ChannelName')}\0`;
+  return `${opaqueRecordPreimage(
+    'client-server',
+    requireNoNul(channelName, 'ChannelName')
+  )}\0`;
 }
 
 function clientServerKey(channelName: string, serverRid: RoutingId) {
-  return storeKey(`${clientServerPrefix(channelName)}${routingIdHexSegment(serverRid)}`);
-}
-
-// {hex(RoutingId)}: lowercase hex of the RoutingId's raw bytes
-// (21-location-runtime.md#2.4).
-function routingIdHexSegment(rid: RoutingId): string {
-  return encodeRoutingIdStorageHex(rid).toLowerCase();
+  return storeKey(opaqueRecordPreimage(
+    'client-server',
+    requireNoNul(channelName, 'ChannelName'),
+    routingIdHexSegment(serverRid)
+  ));
 }
 
 function fanoutPrefix(channelName: string): string {
-  return `fanout-publisher\0${requireNoNul(channelName, 'ChannelName')}\0`;
+  return `${opaqueRecordPreimage(
+    'fanout-publisher',
+    requireNoNul(channelName, 'ChannelName')
+  )}\0`;
 }
 
 function fanoutKey(channelName: string, publisherRid: RoutingId) {
-  return storeKey(`${fanoutPrefix(channelName)}${routingIdHexSegment(publisherRid)}`);
+  return storeKey(opaqueRecordPreimage(
+    'fanout-publisher',
+    requireNoNul(channelName, 'ChannelName'),
+    routingIdHexSegment(publisherRid)
+  ));
 }
 
 function spotKey(meshName: string, spotId: string) {
@@ -3567,7 +3580,6 @@ function encodeAuthorityRecord(record: AuthorityRecord): Uint8Array {
   // These fields gate Node-only creation/aggregate recovery.  They are absent
   // from normal authority values (including the golden vector), while the
   // interoperable envelope above remains byte-canonical.
-  if (record.reservationId !== undefined) envelope.reservationId = record.reservationId;
   if (record.terminal !== undefined) envelope.terminal = record.terminal;
   if (record.aggregate !== undefined) envelope.aggregate = canonicalize(record.aggregate);
   if (record.visibleStoreVersion !== undefined) envelope.visibleStoreVersion = record.visibleStoreVersion;
@@ -3583,7 +3595,6 @@ function decodeAuthorityRecord(bytes: Uint8Array): AuthorityRecord {
   const pending = value.pendingCreation as Record<string, unknown> | null;
   const objectKind = runtimePlacementObjectKind(String(allocation.objectKind));
   return {
-    reservationId: typeof value.reservationId === 'string' ? value.reservationId : undefined,
     terminal: value.terminal as AuthorityRecord['terminal'],
     aggregate: value.aggregate === undefined
       ? undefined
@@ -3682,17 +3693,8 @@ function createTerminalRecord(
 ): ZLinkCreationTerminalRecord {
   const publication = request.completion.terminal;
   validateCreationOperation(publication.operation);
-  if (
-    publication.terminalEnvelope.byteLength > MAX_CREATION_TERMINAL_BYTES
-    || publication.terminalEnvelopeSha256.byteLength !== 32
-  ) {
-    throw new RangeError(
-      'Creation terminal envelope must not exceed 1 MiB and requires a SHA-256 digest.'
-    );
-  }
-  const actualSha = createHash('sha256').update(publication.terminalEnvelope).digest();
-  if (!timingSafeEqual(actualSha, Buffer.from(publication.terminalEnvelopeSha256))) {
-    throw new TypeError('Creation terminal envelope SHA-256 does not match its bytes.');
+  if (publication.terminalEnvelope.byteLength > MAX_CREATION_TERMINAL_BYTES) {
+    throw new RangeError('Creation terminal envelope must not exceed 1 MiB.');
   }
   const deadlineMs = publication.operationDeadline.getTime();
   const expiresAtMs = deadlineMs + CREATION_TERMINAL_RETENTION_MS;
@@ -3709,35 +3711,35 @@ function createTerminalRecord(
     validatePayloadSize(request.completion.readyPayload, 'Actor ready payload');
   }
   return {
-    state: request.completion.kind,
     operation: {
       sourceNodeRid: publication.operation.sourceNodeRid,
       sourceNodeGeneration: publication.operation.sourceNodeGeneration,
       operationId: { ...publication.operation.operationId }
     },
-    reservationId: requireText(request.reservationId, 'creation reservation ID'),
-    objectKind: request.key.kind,
     terminalEnvelope: Buffer.from(publication.terminalEnvelope),
-    terminalEnvelopeSha256: Buffer.from(publication.terminalEnvelopeSha256),
     expiresAt: new Date(expiresAtMs),
     storeNow: new Date(now)
   };
 }
 
-function reviveCreationTerminal(
-  record: ZLinkCreationTerminalRecord
+function retainedCreationTerminal(
+  operation: ZLinkCreationOperationIdentity,
+  terminalEnvelope: Uint8Array,
+  expiresAt: Date | undefined,
+  storeNow: Date
 ): ZLinkCreationTerminalRecord {
+  if (expiresAt === undefined) {
+    throw new Error('Retained creation terminal is missing its expiration.');
+  }
   return {
-    ...record,
     operation: {
-      ...record.operation,
-      sourceNodeRid: String(record.operation.sourceNodeRid),
-      operationId: { ...record.operation.operationId }
+      sourceNodeRid: operation.sourceNodeRid,
+      sourceNodeGeneration: operation.sourceNodeGeneration,
+      operationId: { ...operation.operationId }
     },
-    terminalEnvelope: Buffer.from(record.terminalEnvelope),
-    terminalEnvelopeSha256: Buffer.from(record.terminalEnvelopeSha256),
-    expiresAt: reviveDate(record.expiresAt),
-    storeNow: reviveDate(record.storeNow)
+    terminalEnvelope: Buffer.from(terminalEnvelope),
+    expiresAt: new Date(expiresAt),
+    storeNow: new Date(storeNow)
   };
 }
 
@@ -3751,7 +3753,7 @@ function validateCreationOperation(operation: ZLinkCreationOperationIdentity): v
   }
   if (
     operation.sourceNodeGeneration < 1n
-    || operation.sourceNodeGeneration > MAX_GENERATION
+    || operation.sourceNodeGeneration > MAX_U64
     || operation.operationId.high < 0n
     || operation.operationId.high > MAX_U64
     || operation.operationId.low < 0n

package/src/runtime/locations/opaque-record-key.ts

@@ -0,0 +1,26 @@
+import type { RoutingId } from '../../contracts/Common/CoreTypes';
+import type { ZLinkCreationOperationIdentity } from './internal-location-contracts';
+import { encodeRoutingIdStorageHex } from '../routing-id';
+
+export function opaqueRecordPreimage(
+  record: string,
+  ...segments: readonly string[]
+): string {
+  return [record, ...segments].join('\0');
+}
+
+export function creationTerminalPreimage(
+  operation: ZLinkCreationOperationIdentity
+): string {
+  return opaqueRecordPreimage(
+    'creation-terminal',
+    routingIdHexSegment(operation.sourceNodeRid),
+    operation.sourceNodeGeneration.toString(),
+    operation.operationId.high.toString(16).padStart(16, '0')
+      + operation.operationId.low.toString(16).padStart(16, '0')
+  );
+}
+
+export function routingIdHexSegment(routingId: RoutingId): string {
+  return encodeRoutingIdStorageHex(routingId).toLowerCase();
+}

package/src/runtime/locations/runtime.ts

@@ -132,6 +132,13 @@ export class ZLinkOwnerCleanupError extends Error {
   }
 }
 
+export class ZLinkOwnerLeaseClaimError extends Error {
+  constructor(readonly kind: 'conflict' | 'generationExhausted') {
+    super(`Owner lease claim failed with '${kind}'.`);
+    this.name = 'ZLinkOwnerLeaseClaimError';
+  }
+}
+
 export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   readonly ownerId: string;
   private readonly options: Required<ZLinkLocationOptionOverrides>;
@@ -163,9 +170,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   lastError?: string;
 
   get ownerLeaseUsable(): boolean {
-    return this.ownerLeaseHealthy
-      && (this.ownerLeaseDeadlineMs === undefined
-        || this.monotonicNowMs() < this.ownerLeaseDeadlineMs);
+    return this.ownerToken !== undefined
+      && this.ownerLeaseDeadlineMs !== undefined
+      && this.monotonicNowMs() < this.ownerLeaseDeadlineMs;
   }
 
   constructor(runtimeOptions: ZLinkLocationRuntimeOptions) {
@@ -200,6 +207,11 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     return this.ownerToken;
   }
 
+  closeOwnerLeaseAdmission(error: unknown): void {
+    this.ownerLeaseDeadlineMs = undefined;
+    this.recordFailure(errorMessage(error), 'owner_lease_recovery');
+  }
+
   async reclaimOwnerAuthorities(signal?: AbortSignal): Promise<void> {
     const owner = this.ownerToken;
     if (owner === undefined) {
@@ -303,48 +315,19 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     this.started = true;
     this.ownerCleanupComplete = false;
     this.nodeRidValue = nodeRid;
-    const claimStartedAtMs = this.monotonicNowMs();
-    let claim: Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>;
     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();
+      const claimed = await this.renewOwnerLeaseOnce(signal);
+      if (claimed) {
+        this.scheduleHeartbeat();
+        return;
+      }
+      this.nextLeaseRenewAtMs = this.monotonicNowMs() + this.options.ownerLeaseRenewIntervalMs;
       this.scheduleHeartbeat();
-      return;
-    }
-    const claimCompletedAtMs = this.monotonicNowMs();
-    if (claim.kind !== 'claimed') {
+    } catch (error) {
       this.started = false;
       this.ownerCleanupComplete = true;
-      throw new Error(`Owner lease claim failed with '${claim.kind}'.`);
+      throw error;
     }
-    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?: AbortSignal): Promise<void> {
@@ -395,6 +378,7 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       return await this.claimFreshOwnerLease(signal);
     }
 
+    const wasOwnerLeaseUsable = this.ownerLeaseUsable;
     try {
       const renewStartedAtMs = this.monotonicNowMs();
       const result = await withTimeout(
@@ -431,7 +415,9 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
         result.storeNow
       );
       this.lastError = undefined;
-      for (const handler of this.ownerLeaseRenewedHandlers) handler(result);
+      if (!wasOwnerLeaseUsable) {
+        for (const handler of this.ownerLeaseRenewedHandlers) handler(result);
+      }
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
@@ -443,26 +429,39 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
   }
 
   private async claimFreshOwnerLease(signal?: AbortSignal): Promise<boolean> {
+    const claimStartedAtMs = this.monotonicNowMs();
+    const timeoutDeadline = performance.now() + this.options.ownerLeaseRenewTimeoutMs;
+    let claim: Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>;
+    try {
+      claim = await this.claimOwnerLeaseWithConfirmation(timeoutDeadline, signal);
+    } catch (error) {
+      if (signal?.aborted === true) throw error;
+      if (error instanceof ZLinkOwnerLeaseClaimError) throw error;
+      this.recordOwnerLeaseRenewFailure();
+      this.recordFailure(errorMessage(error), 'owner_lease_claim');
+      return false;
+    }
+    const claimCompletedAtMs = this.monotonicNowMs();
+    if (claim.kind !== 'claimed') {
+      const error = new ZLinkOwnerLeaseClaimError(claim.kind);
+      this.recordFailure(error.message, 'owner_lease_claim');
+      throw error;
+    }
     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);
+        try {
+          await withTimeout(
+            releaseSignal => this.stores.ownerLeaseStore.releaseOwnerLease(
+              claim.token,
+              releaseSignal
+            ),
+            remainingTimeoutMs(timeoutDeadline)
+          );
+        } catch (error) {
+          this.recordFailure(errorMessage(error), 'owner_lease_release');
+        }
         return false;
       }
       this.lastOwnerToken = this.ownerToken;
@@ -487,12 +486,83 @@ export class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
       return true;
     } catch (error) {
       if (signal?.aborted === true) throw error;
-      this.recordOwnerLeaseRenewFailure();
       this.recordFailure(errorMessage(error), 'owner_lease_claim');
       return false;
     }
   }
 
+  private async claimOwnerLeaseWithConfirmation(
+    timeoutDeadline: number,
+    signal?: AbortSignal
+  ): Promise<Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>> {
+    signal?.throwIfAborted();
+    let claim: Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>;
+    try {
+      claim = await withTimeout(
+        (claimSignal) => this.stores.ownerLeaseStore.claimOwnerLease(
+          this.ownerId,
+          this.options.ownerLeaseTtlMs,
+          claimSignal
+        ),
+        remainingTimeoutMs(timeoutDeadline),
+        signal
+      );
+    } catch (error) {
+      if (error instanceof OwnerLeaseRenewTimeoutError) throw error;
+      const confirmed = await this.confirmOwnerLease(error, timeoutDeadline, signal);
+      if (confirmed !== undefined) return confirmed;
+      throw error;
+    }
+    if (claim.kind !== 'conflict') return claim;
+    const conflict = new ZLinkOwnerLeaseClaimError(claim.kind);
+    return await this.confirmOwnerLease(conflict, timeoutDeadline, signal) ?? claim;
+  }
+
+  private async confirmOwnerLease(
+    originalError: unknown,
+    timeoutDeadline: number,
+    signal?: AbortSignal
+  ): Promise<Extract<Awaited<ReturnType<ZLinkOwnerLeaseStore['claimOwnerLease']>>, { kind: 'claimed' }> | undefined> {
+    const confirmationTimeoutMs = remainingTimeoutMs(timeoutDeadline);
+    if (confirmationTimeoutMs <= 0) throw originalError;
+    let confirmed: Awaited<ReturnType<ZLinkOwnerLeaseStore['readOwnerLease']>>;
+    try {
+      confirmed = await withTimeout(
+        readSignal => this.stores.ownerLeaseStore.readOwnerLease(this.ownerId, readSignal),
+        confirmationTimeoutMs
+      );
+    } catch (confirmationError) {
+      this.recordFailure(
+        errorMessage(confirmationError),
+        'owner_lease_claim_confirmation'
+      );
+      throw originalError;
+    }
+    if (confirmed.kind !== 'found' || confirmed.token.ownerId !== this.ownerId) {
+      throw originalError;
+    }
+    if (signal?.aborted === true) {
+      try {
+        await withTimeout(
+          releaseSignal => this.stores.ownerLeaseStore.releaseOwnerLease(
+            confirmed.token,
+            releaseSignal
+          ),
+          remainingTimeoutMs(timeoutDeadline)
+        );
+      } catch (releaseError) {
+        this.recordFailure(errorMessage(releaseError), 'owner_lease_release');
+      }
+      throw originalError;
+    }
+    return {
+      kind: 'claimed',
+      token: confirmed.token,
+      leaseExpiresAt: confirmed.leaseExpiresAt,
+      storeNow: confirmed.storeNow
+    };
+  }
+
   private setOwnerLeaseDeadline(
     requestStartedAtMs: number,
     requestCompletedAtMs: number,
@@ -1106,21 +1176,45 @@ async function withTimeout<T>(
     ? timeoutController.signal
     : AbortSignal.any([signal, timeoutController.signal]);
   let timeout: ReturnType<typeof setTimeout> | undefined;
+  let abort: (() => void) | undefined;
   const deadline = new Promise<never>((_resolve, reject) => {
     timeout = setTimeout(() => {
-      const error = new Error(`Owner lease renewal exceeded ${timeoutMs}ms.`);
+      const error = new OwnerLeaseRenewTimeoutError(timeoutMs);
       timeoutController.abort(error);
       reject(error);
     }, timeoutMs);
     timeout.unref();
   });
+  const cancellation = signal === undefined
+    ? undefined
+    : new Promise<never>((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+      });
   try {
-    return await Promise.race([action(operationSignal), deadline]);
+    signal?.throwIfAborted();
+    return await Promise.race(
+      cancellation === undefined
+        ? [action(operationSignal), deadline]
+        : [action(operationSignal), deadline, cancellation]
+    );
   } finally {
     if (timeout !== undefined) clearTimeout(timeout);
+    if (abort !== undefined) signal?.removeEventListener('abort', abort);
   }
 }
 
+class OwnerLeaseRenewTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Owner lease renewal exceeded ${timeoutMs}ms.`);
+    this.name = 'OwnerLeaseRenewTimeoutError';
+  }
+}
+
+function remainingTimeoutMs(timeoutDeadline: number): number {
+  return Math.max(0, timeoutDeadline - performance.now());
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }