@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/host/spot-address-transport.ts

@@ -336,7 +336,8 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
         instanceSpot: call.instanceSpot,
         timeoutMs: deadline.requireRemaining(),
         signal: deadline.signal,
-        metadata: call.metadata
+        metadata: call.metadata,
+        onAdmitted: call.onAdmitted
       }),
       deadline.signal
     );
@@ -416,7 +417,8 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
           encoded,
           deadlineUnixMs,
           call.sourceSpot === undefined ? undefined : String(call.sourceSpot.routingId),
-          call.metadata
+          call.metadata,
+          call.onAdmitted
         ),
       deadline.signal
     );

package/src/runtime/host/spot-runtime-options-factory.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
 import { ZLinkSpotRelocationCoordinationMode, ZLinkUserSpotExecutionMode } from '../../contracts';
 import {
@@ -137,6 +138,15 @@ export class ZLinkSpotRuntimeOptionsFactory {
         }
         await runtime.dispatchEntryActorJoin(meshName, actor, handoffBacklog);
       },
+      admitEntryActorPacketPrefix: (meshName, actorId, records) => {
+        const runtime = this.options.spotNodeRuntime();
+        if (runtime === undefined) {
+          throw new ZLinkConfigurationException(
+            'Entry Actor replay requires the MeshNode runtime.'
+          );
+        }
+        return runtime.admitEntryActorPacketPrefix(meshName, actorId, records);
+      },
       executeEntryActor: (meshName, actorId, operation) => {
         const runtime = this.options.spotNodeRuntime();
         if (runtime === undefined) {
@@ -278,8 +288,9 @@ export class ZLinkSpotRuntimeOptionsFactory {
         this.options.spotNodeRuntime()?.meshNode(meshName) as never,
       spotRouteResolver: this.options.createLocationSpotRouteResolver(),
       actorResolver: (actorId) => {
-        const state = this.options.actorManager()?.getState(actorId);
-        return state?.isMoving === true ? undefined : state?.actor;
+        const manager = this.options.actorManager();
+        const state = manager?.getState(actorId);
+        return state?.isMoving === true ? undefined : manager?.resolveLocalActor(actorId);
       },
       canonicalActorJoinResolver: (fence) =>
         this.options.boundSessionRelay.actorJoins.prepareCanonicalActorJoin({
@@ -297,14 +308,14 @@ export class ZLinkSpotRuntimeOptionsFactory {
           state?.nativeActorRef === undefined
             ? undefined
             : toFrameworkActorRef(state.nativeActorRef, state.meshName ?? '');
-        const localNodeRid = this.primaryNodeRoutingId();
+        const localNodeRid =
+          state?.meshName === undefined ? undefined : this.meshNodeRoutingId(state.meshName);
         if (
           state?.actor === undefined ||
-          state.spot === undefined ||
           state.remoteActorPacketTarget !== undefined ||
           actorRef === undefined ||
           localNodeRid === undefined ||
-          String(actorRef.nodeRid) !== localNodeRid
+          !routingIdsEqual(actorRef.nodeRid, localNodeRid)
         ) {
           return {};
         }
@@ -333,6 +344,8 @@ export class ZLinkSpotRuntimeOptionsFactory {
         );
       },
       actorTransferRuntime,
+      releaseActorMembers: (meshName, spotId) =>
+        this.options.actorManager()?.releaseSpotActorMembers(meshName, spotId) ?? Promise.resolve(),
       boundSessionRuntime: this.options.boundSessionRelay.boundSessions,
       actorHandoffRuntime: this.options.actorHandoff,
       metrics: this.options.metrics,
@@ -349,11 +362,11 @@ export class ZLinkSpotRuntimeOptionsFactory {
 
   private primaryNodeRoutingId(): string | undefined {
     const node = this.primaryNode();
-    return node === undefined ? undefined : String(node.status().routingId);
+    return node === undefined ? undefined : node.status().routingId;
   }
 
   private meshNodeRoutingId(meshName: string): string | undefined {
     const node = this.options.spotNodeRuntime()?.meshNode(meshName);
-    return node === undefined ? undefined : String(node.status().routingId);
+    return node === undefined ? undefined : node.status().routingId;
   }
 }

package/src/runtime/host/user-spot-creation-coordinator.ts

@@ -1,3 +1,4 @@
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
 import { createHash } from 'node:crypto';
 import {
   type RoutingId,
@@ -131,7 +132,6 @@ export class ZLinkUserSpotCreationCoordinator {
     const contentReference = encodeLocationCreationContent(request.requestPayload);
     const excludedNodeRids = new Set<string>();
     let target: Awaited<ReturnType<ZLinkUserSpotCreationCoordinatorOptions['target']>>;
-    let authorityTarget;
     let reserved: ZLinkObjectReserveResult;
     for (;;) {
       try {
@@ -154,7 +154,7 @@ export class ZLinkUserSpotCreationCoordinator {
           true
         );
       }
-      if (excludedNodeRids.has(String(target.nodeRid))) {
+      if (excludedNodeRids.has(encodeRoutingIdStorageHex(target.nodeRid))) {
         deadline.close();
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted,
@@ -163,7 +163,7 @@ export class ZLinkUserSpotCreationCoordinator {
         );
       }
       const owner = target.owner;
-      authorityTarget = {
+      const authorityTarget = {
         meshName: target.meshName,
         nodeRid: target.nodeRid,
         nodeLifecycleGeneration: target.nodeGeneration,
@@ -217,92 +217,31 @@ export class ZLinkUserSpotCreationCoordinator {
           error
         );
       }
-      if (reserved.kind !== 'placementCapacityExhausted') break;
-      excludedNodeRids.add(String(target.nodeRid));
-    }
-    if (
-      reserved.kind === 'alreadyExists' ||
-      (reserved.kind === 'conflict' &&
-        reserved.current.kind === 'snapshot' &&
-        reserved.current.allocation.objectKind === 'user_spot' &&
-        reserved.current.allocation.stableType === request.stableType)
-    ) {
-      const current = reserved.kind === 'alreadyExists' ? reserved.current : reserved.current;
-      if (current.kind === 'snapshot' && current.allocation.state === 'active') {
+      if (
+        reserved.kind === 'alreadyExists' ||
+        (reserved.kind === 'conflict' &&
+          reserved.current.kind === 'snapshot' &&
+          reserved.current.allocation.objectKind === 'user_spot' &&
+          reserved.current.allocation.stableType === request.stableType)
+      ) {
         if (request.generatedIdentity === true) {
           deadline.close();
           throw spotIdConflict(request.spotId);
         }
-        const spot = spotRef(current, request);
-        deadline.close();
-        return {
-          result: { spot, state: ZLinkSpotCreateState.Existing },
-          spot
-        };
-      }
-      if (current.kind !== 'snapshot' || !sameCreationTarget(current, authorityTarget)) {
-        deadline.close();
-        if (request.generatedIdentity === true) {
-          throw spotIdConflict(request.spotId);
-        }
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestFailed,
-          'User Spot creation requires a remote generation-fenced create operation.'
-        );
-      }
-      if (current.allocation.state === 'reserved' && !target.isLocal) {
         try {
-          return await this.remoteCreate(
-            request,
-            current,
-            target.nodeRid,
-            target.nodeGeneration,
-            deadlineUnixMs,
-            deadlineMs
-          );
-        } finally {
-          deadline.close();
-        }
-      }
-      if (current.allocation.state === 'reserved' && target.isLocal) {
-        const pending = current.pendingCreation;
-        const admitted =
-          pending === undefined ? undefined : this.localCreations.get(pending.reservationId);
-        if (admitted === undefined) {
-          try {
-            const spot = await this.awaitReady(request, signal);
-            return {
-              result: { spot, state: ZLinkSpotCreateState.Existing },
-              spot
-            };
-          } finally {
+          const spot = await this.awaitReady(request, signal);
+          if (spot !== undefined) {
             deadline.close();
+            return { result: { spot, state: ZLinkSpotCreateState.Existing }, spot };
           }
-        }
-        try {
-          const result = await admitted;
-          return result.result.state === ZLinkSpotCreateState.Created
-            ? {
-                result: {
-                  ...result.result,
-                  state: ZLinkSpotCreateState.Existing
-                },
-                spot: result.spot
-              }
-            : result;
-        } finally {
+        } catch (error) {
           deadline.close();
+          throw error;
         }
+        continue;
       }
-      try {
-        const spot = await this.awaitReady(request, signal);
-        return {
-          result: { spot, state: ZLinkSpotCreateState.Existing },
-          spot
-        };
-      } finally {
-        deadline.close();
-      }
+      if (reserved.kind !== 'placementCapacityExhausted') break;
+      excludedNodeRids.add(encodeRoutingIdStorageHex(target.nodeRid));
     }
     if (reserved.kind === 'typeMismatch') {
       deadline.close();
@@ -478,7 +417,7 @@ export class ZLinkUserSpotCreationCoordinator {
           current.allocation.stableType === record.stableType &&
           current.objectGeneration === record.reservation.objectGeneration &&
           current.authorityOwnerGeneration === record.reservation.authorityOwnerGeneration &&
-          String(current.allocation.descriptor.rid) === record.reservation.targetNodeRid &&
+          routingIdsEqual(current.allocation.descriptor.rid, record.reservation.targetNodeRid) &&
           current.allocation.descriptorLifecycleGeneration ===
             record.reservation.targetNodeGeneration &&
           current.ownerId === record.reservation.targetOwnerId &&
@@ -532,7 +471,7 @@ export class ZLinkUserSpotCreationCoordinator {
     try {
       local = await materialize(requestPayload, current, signal ?? new AbortController().signal);
       if (local.state === ZLinkSpotCreateState.Rejected) {
-        local.publication?.abort();
+        await local.publication?.abort();
         await this.options.store.abort(
           {
             key: { kind: 'user_spot', globalId: record.spotId },
@@ -609,13 +548,15 @@ export class ZLinkUserSpotCreationCoordinator {
         committed.ready.allocation.descriptor.meshName,
         readySpotRoute(record.spotId, committed.ready)
       );
-      local.publication?.publish();
+      await local.publication?.publish();
       return {
         result: { spot: readySpot, state: local.state, reply: local.reply },
         spot: readySpot
       };
     } catch (error) {
-      local?.publication?.abort();
+      const publicationCleanup = await Promise.allSettled([
+        Promise.resolve().then(() => local?.publication?.abort())
+      ]);
       const cleanupDeadline = createDeadline(
         this.options.cleanupTimeoutMs ?? DEFAULT_USER_SPOT_CLEANUP_TIMEOUT_MS
       );
@@ -644,7 +585,7 @@ export class ZLinkUserSpotCreationCoordinator {
         waitForAbort(discard?.(cleanupSignal) ?? Promise.resolve(), cleanupSignal)
       ]);
       cleanupDeadline.close();
-      const cleanupErrors = cleanup
+      const cleanupErrors = [...publicationCleanup, ...cleanup]
         .filter((item): item is PromiseRejectedResult => item.status === 'rejected')
         .map((item) => item.reason);
       if (cleanupErrors.length > 0) {
@@ -774,12 +715,25 @@ export class ZLinkUserSpotCreationCoordinator {
   private async awaitReady(
     request: ZLinkUserSpotCreationRequest,
     signal: AbortSignal
-  ): Promise<SpotRef> {
+  ): Promise<SpotRef | undefined> {
     const key = encodeAuthorityKey('user_spot', String(request.spotId));
     for (;;) {
       signal.throwIfAborted();
       const current = await this.options.store.readAuthority(key, signal);
-      if (current.kind === 'snapshot' && current.allocation.state === 'active') {
+      if (current.kind === 'missing') return undefined;
+      if (
+        current.allocation.objectKind !== 'user_spot' ||
+        current.allocation.stableType !== request.stableType
+      ) {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotTypeMismatch,
+          `User Spot '${String(request.spotId)}' has another stable type.`
+        );
+      }
+      if (
+        current.allocation.state === 'active' &&
+        decodeServiceClosingSpotAuthority(current.payload) === undefined
+      ) {
         return spotRef(current, request);
       }
       await wait(this.options.pollIntervalMs ?? DEFAULT_USER_SPOT_POLL_INTERVAL_MS, signal);
@@ -931,7 +885,7 @@ function requireCloseTarget(
     decoded.ownerLeaseGeneration !== current.ownerLeaseGeneration ||
     allocation.objectKind !== 'user_spot' ||
     allocation.state !== 'active' ||
-    String(allocation.descriptor.rid) !== fence.nodeRid ||
+    !routingIdsEqual(allocation.descriptor.rid, fence.nodeRid) ||
     (fence.meshName !== undefined && allocation.descriptor.meshName !== fence.meshName) ||
     (fence.nodeGeneration !== undefined &&
       allocation.descriptorLifecycleGeneration !== fence.nodeGeneration) ||
@@ -1057,19 +1011,6 @@ export function decodeLocationCreationContent(
   return payload;
 }
 
-function sameCreationTarget(
-  snapshot: ZLinkAuthoritySnapshot,
-  target: Parameters<ZLinkObjectCreationStore['reserve']>[0]['target']
-): boolean {
-  return (
-    snapshot.allocation.descriptor.meshName === target.meshName &&
-    String(snapshot.allocation.descriptor.rid) === String(target.nodeRid) &&
-    snapshot.allocation.descriptorLifecycleGeneration === target.nodeLifecycleGeneration &&
-    snapshot.ownerId === target.owner.ownerId &&
-    snapshot.ownerLeaseGeneration === target.owner.leaseGeneration
-  );
-}
-
 function remoteCreationFingerprint(record: ServiceUserSpotCreateRecord): string {
   return JSON.stringify(
     {

package/src/runtime/locations/actor-location-claims.ts

@@ -12,6 +12,10 @@ import { ZLinkSpotKind } from '../../contracts/Spots';
 import { ZLinkLocationKeyCodec } from './key-codec';
 import { encodeAuthorityKey } from './authority-key-codec';
 import { routingIdsEqual } from '../routing-id';
+import {
+  decodeActorAuthorityIdentity,
+  rewriteActorAuthorityRoute
+} from '../actors/actor-authority-publication';
 import type { IZLinkLocationLifecycleRuntime, ZLinkOwnershipLostEvent } from './lifecycle-runtime';
 
 export enum ZLinkActorClaimStatus {
@@ -203,41 +207,59 @@ export class ZLinkActorLocationClaims {
     return { status: ZLinkActorClaimStatus.Claimed, claimed, generation: result.generation };
   }
 
-  async notifyJoinedSpot(
+  async commitMembership(
     actorType: string,
-    actorId: string,
-    _spotMeshName: string,
+    actorRef: ActorRef,
+    authorityOwnerGeneration: bigint,
     spotId: RoutingId,
     spotGeneration: bigint,
-    membershipEpoch: bigint,
+    spotKind: ZLinkSpotKind.Entry | ZLinkSpotKind.User,
     ownerNodeGeneration: bigint
   ): Promise<void> {
-    await this.renew(actorType, actorId, (row) => ({
-      ...row,
-      spotKind: ZLinkSpotKind.User,
-      spotId,
-      spotGeneration,
-      membershipEpoch,
-      ownerNodeGeneration
-    }));
-  }
-
-  async notifyLeftSpot(
-    actorType: string,
-    actorId: string,
-    entrySpotId: RoutingId,
-    entrySpotGeneration: bigint,
-    membershipEpoch: bigint,
-    ownerNodeGeneration: bigint
-  ): Promise<void> {
-    await this.renew(actorType, actorId, (row) => ({
-      ...row,
-      spotKind: ZLinkSpotKind.Entry,
-      spotId: entrySpotId,
-      spotGeneration: entrySpotGeneration,
-      membershipEpoch,
-      ownerNodeGeneration
-    }));
+    const actorId = actorRef.actorId;
+    const store = this.authorityStore;
+    const owner = this.runtime.currentOwnerToken;
+    if (store === undefined || owner === undefined) {
+      throw new Error('Actor membership commit requires Location Store authority and owner.');
+    }
+    const key = encodeAuthorityKey('actor', actorId);
+    const current = await store.readAuthority(key);
+    if (
+      !matchesActorAuthority(current, actorRef, owner) ||
+      current.allocation.stableType !== actorType ||
+      current.authorityOwnerGeneration !== authorityOwnerGeneration ||
+      current.allocation.descriptorLifecycleGeneration !== ownerNodeGeneration
+    ) {
+      throw new Error(`Actor '${actorId}' membership authority fence does not match.`);
+    }
+    const identity = decodeActorAuthorityIdentity(current.payload, current.objectGeneration);
+    if (
+      identity === undefined ||
+      identity.actorType !== actorType ||
+      identity.ownerNodeGeneration !== ownerNodeGeneration ||
+      identity.owner.ownerId !== owner.ownerId ||
+      identity.owner.leaseGeneration !== owner.leaseGeneration ||
+      !routingIdsEqual(identity.actor.nodeRid, actorRef.nodeRid) ||
+      identity.meshName !== actorRef.meshName
+    ) {
+      throw new Error(`Actor '${actorId}' membership authority identity does not match.`);
+    }
+    const result = await store.compareExchangeAuthority(key, current.storeVersion, {
+      kind: 'put',
+      generationTransition: 'preserve',
+      payload: rewriteActorAuthorityRoute(
+        current.payload,
+        actorRef,
+        String(spotId),
+        spotGeneration,
+        spotKind
+      )
+    });
+    if (result.kind !== 'stored') {
+      throw new Error(
+        `Actor '${actorId}' membership commit was rejected with status ${result.kind}.`
+      );
+    }
   }
 
   async release(_actorType: string, actorId: string, actorRef?: ActorRef): Promise<void> {

package/src/runtime/locations/auto-connect-loop.ts

@@ -55,6 +55,15 @@ export class ZLinkAutoConnectLoop {
     this.scheduleNext();
   }
 
+  async requestPeerReconcile(meshName: string, _peerRid: string): Promise<void> {
+    const controller = this.controller;
+    if (meshName !== this.meshName || controller === undefined) return;
+    // A fresh descriptor scan uses the same RID ordering and connection owner as a periodic tick.
+    await this.lane.run(async () => {
+      if (!controller.signal.aborted) await this.runReconcile(controller.signal);
+    });
+  }
+
   async stop(signal?: AbortSignal): Promise<void> {
     await this.prepareTransportShutdown();
     await this.finishTransportShutdown(signal);
@@ -78,7 +87,11 @@ export class ZLinkAutoConnectLoop {
   }
 
   async tick(signal?: AbortSignal): Promise<void> {
-    const lastTickFailed = await this.lane.run(() => this.lastTickFailed);
+    await this.lane.run(() => this.tickCore(signal));
+  }
+
+  private async tickCore(signal?: AbortSignal): Promise<void> {
+    const lastTickFailed = this.lastTickFailed;
     if (this.changeStampStore?.getMeshNodeChangeStamp !== undefined && !lastTickFailed) {
       try {
         const stamp = await this.changeStampStore.getMeshNodeChangeStamp(this.meshName, signal);
@@ -94,11 +107,10 @@ export class ZLinkAutoConnectLoop {
           return;
         }
         const tickFailed = await this.runReconcile(signal);
-        if (!tickFailed)
-          await this.lane.run(() => {
-            this.lastStamp = stamp;
-            this.lastLiveOwnerSetVersion = liveOwners;
-          });
+        if (!tickFailed) {
+          this.lastStamp = stamp;
+          this.lastLiveOwnerSetVersion = liveOwners;
+        }
         return;
       } catch {
         // A failed stamp read degrades to a full reconcile tick.
@@ -106,18 +118,14 @@ export class ZLinkAutoConnectLoop {
     }
 
     await this.runReconcile(signal);
-    await this.lane.run(() => {
-      this.lastStamp = undefined;
-      this.lastLiveOwnerSetVersion = undefined;
-    });
+    this.lastStamp = undefined;
+    this.lastLiveOwnerSetVersion = undefined;
   }
 
   private async runReconcile(signal?: AbortSignal): Promise<boolean> {
     await this.reconciler.tick(signal);
-    return await this.lane.run(() => {
-      this.lastTickFailed = this.reconciler.storeFailed;
-      return this.lastTickFailed;
-    });
+    this.lastTickFailed = this.reconciler.storeFailed;
+    return this.lastTickFailed;
   }
 
   private scheduleNext(): void {

package/src/runtime/locations/auto-connect-reconciler.ts

@@ -195,15 +195,11 @@ export class ZLinkAutoConnectReconciler {
     }
     const deferringMissingTargets =
       this.monotonicNowMs() < (await this.lane.run(() => this.recoveryDeferUntilMs));
-    let staleCandidates = candidates;
     if (deferringMissingTargets) {
-      const retainedCandidates = new Map(candidates);
       const lastDesired = await this.lane.run(() => [...this.lastDesired]);
       for (const [key, target] of lastDesired) {
         if (!desired.has(key)) desired.set(key, target);
-        if (!retainedCandidates.has(key)) retainedCandidates.set(key, target);
       }
-      staleCandidates = retainedCandidates;
     }
     await this.lane.run(() => {
       this.lastDesired = new Map(desired);
@@ -270,8 +266,6 @@ export class ZLinkAutoConnectReconciler {
       }
     }
 
-    this.executor.disconnectStalePeers?.([...staleCandidates.values()]);
-
     const activeTargets = await this.lane.run(() => [...this.active]);
     for (const [key, target] of activeTargets) {
       if (!desired.has(key)) {

package/src/runtime/locations/auto-connect-types.ts

@@ -32,7 +32,6 @@ export interface ZLinkAutoConnectTarget {
 export interface IZLinkAutoConnectExecutor {
   connect(target: ZLinkAutoConnectTarget): Promise<boolean>;
   disconnect(target: ZLinkAutoConnectTarget): void;
-  disconnectStalePeers?(targets: readonly ZLinkAutoConnectTarget[]): void;
   isDisconnected?(target: ZLinkAutoConnectTarget): boolean;
   onDisconnected?(handler: (endpoint: string) => void): void;
   replaceNotRequired?(targets: readonly ZLinkAutoConnectTarget[]): void;

package/src/runtime/locations/descriptor-publication.ts

@@ -0,0 +1,7 @@
+/** A descriptor Store write failed without a confirmed result (Location runtime section 5). */
+export class ZLinkDescriptorPublicationUnconfirmedError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = 'ZLinkDescriptorPublicationUnconfirmedError';
+  }
+}

package/src/runtime/locations/domain-store-contract.ts

@@ -49,6 +49,11 @@ import type {
  * implement this interface; the framework maps it to the opaque Store SPI.
  */
 export interface ZLinkDomainLocationStore {
+  confirmedCapacity?(
+    key: ZLinkMeshNodeDescriptorKey,
+    limits: ZLinkMeshNodeDescriptor['populationCapacity']
+  ): ZLinkMeshNodeDescriptor['populationCapacity'] | undefined;
+
   updateMeshNode(
     descriptor: ZLinkMeshNodeDescriptor,
     intent: ZLinkLocationWriteIntent,