@zlink-systems/framework 0.10.0 → 0.12.0

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

@@ -92,6 +92,7 @@ const MAX_CREATION_TERMINAL_BYTES = 1024 * 1024;
 const CREATION_TERMINAL_RETENTION_MS = 5 * 60 * 1000;
 const AGGREGATE_COMMIT_RETRY_WINDOW_MS = 5_000;
 const MAX_AGGREGATE_COMMIT_CONFLICT_RETRIES = 64;
+const MAX_DESCRIPTOR_WRITE_RETRIES = 3;
 
 type StoredAuthoritySnapshot = Omit<
   ZLinkAuthoritySnapshot,
@@ -1603,67 +1604,15 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
     intent: ZLinkLocationWriteIntent,
     signal?: AbortSignal
   ): Promise<ZLinkLocationWriteResult> {
-    const leaseKey = ownerKey(descriptor.ownerId);
-    const rowKey = meshKey(descriptor.meshName, descriptor.rid);
-    const [lease, current] = await Promise.all([
-      this.provider.read(leaseKey, signal),
-      this.provider.read(rowKey, signal)
-    ]);
-    if (lease.kind === 'missing') return rejected(lease.storeNow);
-    if (liveOwnerLeaseGeneration(lease) !== descriptor.leaseGeneration) {
-      return rejected(lease.value.storeNow);
-    }
-
-    let generation = 1n;
-    let rowCondition: ZLinkStoreCondition = { kind: 'missing', key: rowKey };
-    if (current.kind === 'found') {
-      const record = decodeCanonicalDescriptorRecord<ZLinkMeshNodeDescriptor>(current.value.bytes);
-      const stored = reviveMeshDescriptor(record.descriptor);
-      generation = descriptorStoreGeneration(record, current.value.version.value);
-      if (sameMeshDescriptor(stored, descriptor)) {
-        return { status: WriteStatus.Stored, generation, updatedAt: current.value.storeNow };
-      }
-      const currentLease = await this.provider.read(ownerKey(stored.ownerId), signal);
-      const currentLeaseGeneration = liveOwnerLeaseGeneration(currentLease);
-      const takeover = canTakeOverStoredLocation(
-        intent,
-        stored.ownerId,
-        stored.leaseGeneration,
-        descriptor.ownerId,
-        descriptor.leaseGeneration,
-        currentLeaseGeneration
-      );
-      const renew = intent === 2
-        && stored.ownerId === descriptor.ownerId
-        && stored.leaseGeneration === descriptor.leaseGeneration
-        && stored.lifecycleGeneration === descriptor.lifecycleGeneration
-        && descriptor.descriptorRevision > stored.descriptorRevision;
-      if (!takeover && !renew) {
-        return {
-          status: WriteStatus.IgnoredStale,
-          generation,
-          updatedAt: current.value.storeNow
-        };
-      }
-      if (takeover) generation += 1n;
-      rowCondition = { kind: 'version', key: rowKey, expected: current.value.version };
-    } else if (intent === 2) {
-      return rejected(lease.value.storeNow);
-    }
-
-    const result = await this.provider.write({
-      conditions: [
-        { kind: 'version', key: leaseKey, expected: lease.value.version },
-        rowCondition
-      ],
-      mutations: [{
-        kind: 'put',
-        key: rowKey,
-        bytes: encodeCanonicalDescriptorRecord(generation, persistMeshDescriptor(descriptor))
-      }]
-    }, signal);
-    if (result.kind === 'conflict') return rejected(result.storeNow);
-    return { status: WriteStatus.Stored, generation, updatedAt: result.storeNow };
+    return this.updateDescriptor(
+      meshKey(descriptor.meshName, descriptor.rid),
+      descriptor,
+      intent,
+      reviveMeshDescriptor,
+      sameMeshDescriptor,
+      canRenewMesh,
+      signal
+    );
   }
 
   override async removeMeshNode(
@@ -2253,12 +2202,15 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
       this.provider.read(rowKey, signal)
     ]);
     if (lease.kind === 'missing') return rejected(lease.storeNow);
-    if (liveOwnerLeaseGeneration(lease) !== descriptor.leaseGeneration) {
+    if (!matchesLiveOwnerLease(
+      lease,
+      descriptor.ownerId,
+      descriptor.leaseGeneration
+    )) {
       return rejected(lease.value.storeNow);
     }
 
     let generation = 1n;
-    let rowCondition: ZLinkStoreCondition = { kind: 'missing', key: rowKey };
     if (current.kind === 'found') {
       const record = decodeCanonicalDescriptorRecord<T>(current.value.bytes);
       const stored = revive(record.descriptor);
@@ -2285,24 +2237,67 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         };
       }
       if (takeover) generation += 1n;
-      rowCondition = { kind: 'version', key: rowKey, expected: current.value.version };
     } else if (intent === 2) {
       return rejected(lease.value.storeNow);
     }
 
-    const result = await this.provider.write({
-      conditions: [
-        { kind: 'version', key: leaseKey, expected: lease.value.version },
-        rowCondition
-      ],
-      mutations: [{
-        kind: 'put',
-        key: rowKey,
-        bytes: encodeCanonicalDescriptorRecord(generation, descriptor)
-      }]
-    }, signal);
-    if (result.kind === 'conflict') return rejected(result.storeNow);
-    return { status: WriteStatus.Stored, generation, updatedAt: result.storeNow };
+    return this.writeDescriptorWithReconciliation(
+      leaseKey,
+      descriptor.ownerId,
+      descriptor.leaseGeneration,
+      lease,
+      rowKey,
+      current,
+      encodeCanonicalDescriptorRecord(generation, descriptor),
+      generation,
+      signal
+    );
+  }
+
+  private async writeDescriptorWithReconciliation(
+    leaseKey: ZLinkStoreKey,
+    ownerId: string,
+    leaseGeneration: bigint,
+    liveLease: Extract<ZLinkStoreReadResult, { kind: 'found' }>,
+    rowKey: ZLinkStoreKey,
+    predecessor: ZLinkStoreReadResult,
+    encodedDescriptor: Uint8Array,
+    generation: bigint,
+    signal?: AbortSignal
+  ): Promise<ZLinkLocationWriteResult> {
+    let currentLease = liveLease;
+    let currentRow = predecessor;
+
+    for (let attempt = 0; attempt <= MAX_DESCRIPTOR_WRITE_RETRIES; attempt += 1) {
+      const rowCondition: ZLinkStoreCondition = currentRow.kind === 'found'
+        ? { kind: 'version', key: rowKey, expected: currentRow.value.version }
+        : { kind: 'missing', key: rowKey };
+      const result = await this.provider.write({
+        conditions: [
+          { kind: 'version', key: leaseKey, expected: currentLease.value.version },
+          rowCondition
+        ],
+        mutations: [{ kind: 'put', key: rowKey, bytes: encodedDescriptor }]
+      }, signal);
+      if (result.kind === 'applied') {
+        return { status: WriteStatus.Stored, generation, updatedAt: result.storeNow };
+      }
+      if (attempt === MAX_DESCRIPTOR_WRITE_RETRIES) return ignoredStale(result.storeNow);
+
+      const [refreshedLease, refreshedRow] = await Promise.all([
+        this.provider.read(leaseKey, signal),
+        this.provider.read(rowKey, signal)
+      ]);
+      if (refreshedLease.kind === 'missing'
+        || !matchesLiveOwnerLease(refreshedLease, ownerId, leaseGeneration)
+        || !sameDescriptorPredecessor(predecessor, refreshedRow)) {
+        return ignoredStale(result.storeNow);
+      }
+
+      currentLease = refreshedLease;
+      currentRow = refreshedRow;
+    }
+    throw new Error('Descriptor write retry loop exhausted unexpectedly.');
   }
 
   private async removeDescriptor<T extends OwnedDescriptor>(
@@ -3888,9 +3883,36 @@ function sameLiveOwner(
   lease: ZLinkStoreReadResult,
   snapshot: StoredAuthoritySnapshot
 ): boolean {
-  if (liveOwnerLeaseGeneration(lease) !== snapshot.ownerLeaseGeneration) return false;
-  const owner = decodeOwnerRecord((lease as Extract<ZLinkStoreReadResult, { kind: 'found' }>).value.bytes);
-  return owner.ownerId === snapshot.ownerId;
+  if (lease.kind === 'missing') return false;
+  return matchesLiveOwnerLease(
+    lease,
+    snapshot.ownerId,
+    snapshot.ownerLeaseGeneration
+  );
+}
+
+function matchesLiveOwnerLease(
+  lease: Extract<ZLinkStoreReadResult, { kind: 'found' }>,
+  ownerId: string,
+  leaseGeneration: bigint
+): boolean {
+  if (lease.value.expiresAt === undefined
+    || lease.value.expiresAt.getTime() <= lease.value.storeNow.getTime()) {
+    return false;
+  }
+  const owner = decodeOwnerRecord(lease.value.bytes);
+  return owner.ownerId === ownerId
+    && BigInt(owner.leaseGeneration) === leaseGeneration;
+}
+
+function sameDescriptorPredecessor(
+  expected: ZLinkStoreReadResult,
+  current: ZLinkStoreReadResult
+): boolean {
+  if (expected.kind === 'missing' || current.kind === 'missing') {
+    return expected.kind === current.kind;
+  }
+  return Buffer.from(expected.value.bytes).equals(Buffer.from(current.value.bytes));
 }
 
 function liveOwnerLeaseGeneration(
@@ -4113,6 +4135,14 @@ function sameFanoutDescriptor(
   return descriptorFingerprint(left, ['updatedAt']) === descriptorFingerprint(right, ['updatedAt']);
 }
 
+function canRenewMesh(
+  current: ZLinkMeshNodeDescriptor,
+  next: ZLinkMeshNodeDescriptor
+): boolean {
+  return sameOwnerGeneration(current, next)
+    && next.descriptorRevision > current.descriptorRevision;
+}
+
 function canRenewClientServer(
   current: ZLinkClientServerServerDescriptor,
   next: ZLinkClientServerServerDescriptor
@@ -4201,6 +4231,14 @@ function rejected(updatedAt: Date): ZLinkLocationWriteResult {
   };
 }
 
+function ignoredStale(updatedAt: Date): ZLinkLocationWriteResult {
+  return {
+    status: WriteStatus.IgnoredStale,
+    generation: 0n,
+    updatedAt
+  };
+}
+
 function requireOwnerInput(ownerId: string, leaseTtlMs: number): void {
   if (Buffer.byteLength(ownerId, 'utf8') < 1 || ownerId.includes('\0')) {
     throw new TypeError('Owner ID must be non-empty UTF-8 without NUL.');

package/src/runtime/spots/spot-node-runtime-manager.ts

@@ -142,22 +142,6 @@ export interface ZLinkSpotNodeRuntimeManagerOptions {
   };
 }
 
-interface ZLinkPublishSlotWaiter {
-  readonly resolve: (acquired: boolean) => void;
-  readonly reject: (error: unknown) => void;
-  readonly signal?: AbortSignal;
-  abortHandler?: () => void;
-  timeout?: ReturnType<typeof setTimeout>;
-  deadlineMs?: number;
-  settled: boolean;
-}
-
-interface ZLinkPublishSlotQueue {
-  readonly waiters: Array<ZLinkPublishSlotWaiter | undefined>;
-  head: number;
-  count: number;
-}
-
 export class ZLinkSpotNodeRuntimeManager {
   private readonly meshNodes = new Map<string, ZLinkBackendMeshNode>();
   private readonly meshPumps = new Map<string, ZLinkMeshDispatchPump>();
@@ -168,8 +152,6 @@ export class ZLinkSpotNodeRuntimeManager {
     string,
     ReturnType<ZLinkBackendMeshNode['createPublisher']>
   >();
-  private readonly activePublishes = new Set<string>();
-  private readonly publishSlotWaiters = new Map<string, ZLinkPublishSlotQueue>();
   private disposed = false;
   private readonly autoConnectLoops: ZLinkAutoConnectLoop[] = [];
   private readonly publishedMeshNodeDescriptors =
@@ -829,7 +811,6 @@ export class ZLinkSpotNodeRuntimeManager {
     this.meshPumps.clear();
     const publishers = [...this.publishers.values()];
     this.publishers.clear();
-    this.rejectPublishSlotWaiters(runtimeShutdownError());
     const errors: unknown[] = [];
     const settle = async (operations: readonly Promise<unknown>[]) => {
       const results = await Promise.allSettled(operations);
@@ -1120,76 +1101,32 @@ export class ZLinkSpotNodeRuntimeManager {
     if (publisher === undefined) {
       throw new ZLinkConfigurationException(`RouteMesh '${meshName}' publisher is not started.`);
     }
-    const sendTimeoutMs = this.options.registration.spotNodes
-      .get(meshName)?.publisherConfig?.sendTimeoutMs ?? 1000;
-    const slot = this.acquirePublishSlot(meshName, sendTimeoutMs, signal);
-    if (slot === false) {
-      // The bounded executor-admission tokens are exhausted. Do not retain the
-      // payload, cancellation state, or a timer for this hard-overload call.
-      return Promise.resolve(this.publishTimedOut());
-    }
-    if (slot === true) {
-      return this.executePublish(
-        publisher,
-        meshName,
-        channelName,
-        topic,
-        packetName,
-        event,
-        metadata
-      );
-    }
-    return slot.then((acquired) => acquired
-      ? this.executePublish(
-        publisher,
-        meshName,
-        channelName,
-        topic,
-        packetName,
-        event,
-        metadata
-      )
-      : this.publishTimedOut());
+    return this.executePublish(publisher, channelName, topic, packetName, event, metadata);
   }
 
   private async executePublish(
     publisher: ReturnType<ZLinkBackendMeshNode['createPublisher']>,
-    meshName: string,
     channelName: string,
     topic: string,
     packetName: string | undefined,
     event: Message,
     metadata: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
-    // The slot is the source-local admission boundary. Once publishAsync takes
-    // the owned frames, target processing cannot change the caller terminal.
-    // Call-scoped flow (spec 27 §4): the fanout envelope flow pair does not
-    // outlive this publish call.
-    try {
-      const parts = runWithOutboundFlow(
-        this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true,
-        () => encodeChannelPublishEnvelopeParts(
-          channelName,
-          topic,
-          packetName,
-          event,
-          undefined,
-          this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true,
-          metadata
-        )
-      );
-      const processing = publisher.publishAsync(
+    const parts = runWithOutboundFlow(
+      this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true,
+      () => encodeChannelPublishEnvelopeParts(
         channelName,
         topic,
-        parts,
+        packetName,
+        event,
         undefined,
-        undefined
-      );
-      void Promise.resolve(processing).catch(() => undefined);
-      return Promise.resolve({ status: ZLinkSubmitStatus.Submitted });
-    } finally {
-      this.releasePublishSlot(meshName);
-    }
+        this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true,
+        metadata
+      )
+    );
+    const processing = publisher.publishAsync(channelName, topic, parts, undefined, undefined);
+    void Promise.resolve(processing).catch(() => undefined);
+    return Promise.resolve({ status: ZLinkSubmitStatus.Submitted });
   }
 
   tryPublish(
@@ -1242,163 +1179,6 @@ export class ZLinkSpotNodeRuntimeManager {
     }
   }
 
-  private acquirePublishSlot(
-    meshName: string,
-    timeoutMs: number,
-    signal?: AbortSignal
-  ): boolean | Promise<boolean> {
-    if (!this.activePublishes.has(meshName)) {
-      this.activePublishes.add(meshName);
-      return true;
-    }
-    const waiterCapacity = Math.max(
-      1,
-      this.options.registration.spotNodes
-        .get(meshName)?.publisherConfig?.sendHighWaterMark ?? 1
-    );
-    const queue = this.publishSlotWaiters.get(meshName) ?? {
-      waiters: [],
-      head: 0,
-      count: 0
-    };
-    if (queue.count >= waiterCapacity) {
-      // This call has no bounded executor-admission token. Fail without
-      // retaining its payload in a pending work queue.
-      return false;
-    }
-    return new Promise<boolean>((resolve, reject) => {
-      const waiter: ZLinkPublishSlotWaiter = {
-        resolve,
-        reject,
-        signal,
-        settled: false
-      };
-      if (timeoutMs !== -1) {
-        waiter.deadlineMs = performance.now() + Math.max(0, timeoutMs);
-      }
-      queue.waiters.push(waiter);
-      queue.count += 1;
-      this.publishSlotWaiters.set(meshName, queue);
-      if (timeoutMs !== -1) {
-        waiter.timeout = setTimeout(() => this.settlePublishSlotWaiter(
-          meshName,
-          waiter,
-          false
-        ), Math.max(0, timeoutMs));
-      }
-      if (signal !== undefined) {
-        waiter.abortHandler = () => this.rejectPublishSlotWaiter(
-          meshName,
-          waiter,
-          signal.reason ?? createAbortError()
-        );
-        signal.addEventListener('abort', waiter.abortHandler, { once: true });
-      }
-    });
-  }
-
-  private publishTimedOut(): ZLinkSubmitResult {
-    return { status: ZLinkSubmitStatus.TimedOut };
-  }
-
-  private releasePublishSlot(meshName: string): void {
-    const queue = this.publishSlotWaiters.get(meshName);
-    while (queue !== undefined && queue.count > 0) {
-      const waiter = this.takePublishSlotWaiter(queue);
-      if (waiter === undefined) continue;
-      if (waiter.settled) continue;
-      if (waiter.deadlineMs !== undefined && performance.now() >= waiter.deadlineMs) {
-        this.cleanupPublishSlotWaiter(waiter);
-        waiter.settled = true;
-        waiter.resolve(false);
-        continue;
-      }
-      this.cleanupPublishSlotWaiter(waiter);
-      waiter.settled = true;
-      waiter.resolve(true);
-      if (queue.count === 0) this.publishSlotWaiters.delete(meshName);
-      return;
-    }
-    this.publishSlotWaiters.delete(meshName);
-    this.activePublishes.delete(meshName);
-  }
-
-  private settlePublishSlotWaiter(
-    meshName: string,
-    waiter: ZLinkPublishSlotWaiter,
-    acquired: boolean
-  ): void {
-    if (waiter.settled) return;
-    waiter.settled = true;
-    this.removePublishSlotWaiter(meshName, waiter);
-    this.cleanupPublishSlotWaiter(waiter);
-    waiter.resolve(acquired);
-  }
-
-  private rejectPublishSlotWaiter(
-    meshName: string,
-    waiter: ZLinkPublishSlotWaiter,
-    error: unknown
-  ): void {
-    if (waiter.settled) return;
-    waiter.settled = true;
-    this.removePublishSlotWaiter(meshName, waiter);
-    this.cleanupPublishSlotWaiter(waiter);
-    waiter.reject(error);
-  }
-
-  private removePublishSlotWaiter(meshName: string, waiter: ZLinkPublishSlotWaiter): void {
-    const queue = this.publishSlotWaiters.get(meshName);
-    if (queue === undefined) return;
-    const index = queue.waiters.indexOf(waiter, queue.head);
-    if (index >= 0) {
-      queue.waiters[index] = undefined;
-      queue.count -= 1;
-      this.compactPublishSlotWaiters(queue);
-    }
-    if (queue.count === 0) this.publishSlotWaiters.delete(meshName);
-  }
-
-  private cleanupPublishSlotWaiter(waiter: ZLinkPublishSlotWaiter): void {
-    if (waiter.timeout !== undefined) clearTimeout(waiter.timeout);
-    if (waiter.abortHandler !== undefined) {
-      waiter.signal?.removeEventListener('abort', waiter.abortHandler);
-    }
-  }
-
-  private rejectPublishSlotWaiters(error: unknown): void {
-    for (const [meshName, queue] of this.publishSlotWaiters) {
-      let waiter: ZLinkPublishSlotWaiter | undefined;
-      while ((waiter = this.takePublishSlotWaiter(queue)) !== undefined) {
-        this.rejectPublishSlotWaiter(meshName, waiter, error);
-      }
-      this.publishSlotWaiters.delete(meshName);
-    }
-    this.activePublishes.clear();
-  }
-
-  private takePublishSlotWaiter(queue: ZLinkPublishSlotQueue): ZLinkPublishSlotWaiter | undefined {
-    while (queue.head < queue.waiters.length && queue.waiters[queue.head] === undefined) {
-      queue.head += 1;
-    }
-    const waiter = queue.waiters[queue.head];
-    if (waiter === undefined) return undefined;
-    queue.waiters[queue.head] = undefined;
-    queue.head += 1;
-    queue.count -= 1;
-    this.compactPublishSlotWaiters(queue);
-    return waiter;
-  }
-
-  private compactPublishSlotWaiters(queue: ZLinkPublishSlotQueue): void {
-    if (queue.count === 0) {
-      queue.waiters.length = 0;
-      queue.head = 0;
-    } else if (queue.head >= 1024 && queue.head * 2 >= queue.waiters.length) {
-      queue.waiters.splice(0, queue.head);
-      queue.head = 0;
-    }
-  }
 }
 
 function runtimeShutdownError(): ZLinkFrameworkException {

package/src/runtime/spots/spot-serial-turn-executor.ts

@@ -38,14 +38,7 @@ export class ZLinkSpotSerialTurnExecutor {
   ) {
     this.scheduler = new ZLinkSerialExecutionQueue(
       (record) => this.runQueuedRecord(record),
-      {
-        ...schedulerOptions,
-        capacityError: schedulerOptions?.capacityError ?? (() =>
-          createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.WorkerQueueFull,
-            'Spot execution queue capacity was exceeded.'
-          ))
-      }
+      schedulerOptions
     );
   }