@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/spots/spot-entry-activation.ts

@@ -29,7 +29,6 @@ import { routingIdsEqual } from '../routing-id';
 import { ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
 import type {
   ZLinkBackendActorRecvInfo,
-  ZLinkBackendReceived,
   ZLinkBackendSpot,
   ZLinkBackendSpotNode,
   ZLinkBackendTopicMessage
@@ -81,7 +80,6 @@ interface ZLinkEntrySpotActivationOptions {
   readonly actorRequestHandlers?: readonly ZLinkEntrySpotActorRequestHandlerRegistration[];
   readonly nativeSpot: ZLinkBackendSpot;
   readonly nativeNode: ZLinkBackendSpotNode;
-  readonly createReceived: () => ZLinkBackendReceived;
   readonly createTopicMessage: () => ZLinkBackendTopicMessage;
   readonly nodeRid: RoutingId;
   readonly spotNodeName: string;
@@ -90,7 +88,6 @@ interface ZLinkEntrySpotActivationOptions {
   readonly spotPublisherClient?: ZLinkSpotPublisherClient;
   readonly routedTransport?: ZLinkSpotRoutedTransport;
   readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
-  readonly channelMeshNameForChannel?: (channelName: string) => string | undefined;
   readonly providerResolver?: ZLinkProviderResolver;
   readonly dispatchErrors?: ZLinkDispatchErrorReporter;
   readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
@@ -101,7 +98,7 @@ interface ZLinkEntrySpotActivationOptions {
   readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
   readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
   readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-  readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+  readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
 }
 
 export class ZLinkEntrySpotActivation {
@@ -123,6 +120,11 @@ export class ZLinkEntrySpotActivation {
   readonly context: ZLinkEntrySpotContext;
 
   constructor(private readonly options: ZLinkEntrySpotActivationOptions) {
+    if ((options.detachedTaskRunner as unknown) === undefined) {
+      throw new ZLinkConfigurationException(
+        'Entry Spot activation requires a detached task runner.'
+      );
+    }
     this.serial = new ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
     this.spotSerialExecutor = new ZLinkSpotSerialExecutor(
       this.serial,
@@ -147,7 +149,7 @@ export class ZLinkEntrySpotActivation {
     this.workerRuntime = options.workerRuntime ?? new ZLinkWorkerRuntime();
     this.context = createEntrySpotContext({
       spotId: String(options.nativeSpot.routingId),
-      objectGeneration: toContextGeneration(entrySpotGeneration(options.nativeSpot)),
+      objectGeneration: entrySpotGeneration(options.nativeSpot),
       nodeRid: options.nodeRid,
       handlers: this.handlers,
       outbound: this.outbound,
@@ -197,8 +199,6 @@ export class ZLinkEntrySpotActivation {
           target.remoteBoundSessionTarget,
           target.fallbackActorRef
         ),
-      onRemoteBoundSessionTarget: (targetActorId, target) =>
-        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
       onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
         this.options.boundSessionRuntime
@@ -327,7 +327,7 @@ export class ZLinkEntrySpotActivation {
     await cleanup(() => this.actorDispatch?.dispose());
     await cleanup(() => this.timers.dispose());
     await cleanup(() => this.spotSerialExecutor.close());
-    await cleanup(() => disposeLifecycleHandlers(this.entrySpot));
+    await cleanup(() => disposeLifecycleHandlers(this.entrySpot, this.options.detachedTaskRunner));
     await cleanup(() => this.options.nativeSpot.dispose());
     if (this.initialized) {
       this.lifecycleMetrics.closed('entry');
@@ -374,6 +374,10 @@ export class ZLinkEntrySpotActivation {
     }
   }
 
+  executeActor<T>(actorId: string, operation: () => Promise<T>): Promise<T> {
+    return this.spotSerialExecutor.executeActor(actorId, operation);
+  }
+
   /**
    * Entry Spot membership does not have an application admission callback.
    * The shared core round-trip therefore accepts a valid returning Actor and
@@ -382,7 +386,6 @@ export class ZLinkEntrySpotActivation {
   private attachActorJoinDispatch(): void {
     const dispatch = new ZLinkSpotActorJoinDispatch({
       nativeSpot: this.options.nativeSpot,
-      createReceived: this.options.createReceived,
       createTopicMessage: this.options.createTopicMessage,
       serial: this.serial,
       actors: {
@@ -396,7 +399,6 @@ export class ZLinkEntrySpotActivation {
                 kind: 'enabled',
                 runtime: this.options.actorTransferRuntime
               },
-        commitNativeActor: (actor) => this.commitEntryActorTransaction(actor),
         commitTransferredActor: async (actor, backlog) => {
           await this.commitEntryActorTransaction(actor);
           return await this.replayActorBacklog(actor, backlog);
@@ -404,23 +406,10 @@ export class ZLinkEntrySpotActivation {
       },
       packets: {
         handle: (delivery) => this.dispatchActorPacket(delivery),
-        bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => {
+        bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
           if (routingIdsEqual(sourceNodeRid, this.options.nativeNode.routingId)) {
             return;
           }
-          const target =
-            declaredTarget ??
-            this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(
-              sourceNodeRid,
-              sourceSessionRid
-            );
-          if (target !== undefined) {
-            this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(actor.actorId, {
-              ...target,
-              sessionNodeRid: sourceNodeRid,
-              sessionRid: sourceSessionRid
-            });
-          }
           this.options.nativeNode.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
         },
         replyNoBind: (info, parts, result) => this.replyActorNoBind(info, parts, result)
@@ -552,15 +541,6 @@ function notifyEntryActorJoined(entrySpot: ZLinkEntrySpot, actor: ZLinkActor): P
   return callback === undefined ? Promise.resolve() : callback.call(entrySpot, actor);
 }
 
-function toContextGeneration(generation: bigint): number {
-  if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
-    throw new ZLinkConfigurationException(
-      `Entry Spot object generation '${generation}' cannot be represented by the Node.js public context.`
-    );
-  }
-  return Number(generation);
-}
-
 function entrySpotGeneration(spot: ZLinkBackendSpot): bigint {
   return (
     spot.lifecycleGeneration ??

package/src/runtime/spots/spot-lifecycle-metrics.ts

@@ -1,3 +1,4 @@
+import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
 import type { ZLinkRuntimeMetrics } from '../diagnostics';
 
 export type ZLinkSpotMetricKind = 'entry' | 'user';
@@ -6,10 +7,10 @@ export class ZLinkSpotLifecycleMetrics {
   constructor(private readonly metrics?: ZLinkRuntimeMetrics) {}
 
   opened(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change('zlink.spot.count', 1, { kind });
+    this.metrics?.change(METRIC_NAMES.SpotCount, 1, { kind });
   }
 
   closed(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change('zlink.spot.count', -1, { kind });
+    this.metrics?.change(METRIC_NAMES.SpotCount, -1, { kind });
   }
 }

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

@@ -1,12 +1,8 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind,
-  wireReplyFailureException
-} from '../framework-errors-internal';
 import { randomUUID } from 'node:crypto';
 import {
+  type ZLinkMessageSerializer,
   ZLinkFrameworkException,
+  ZLinkSpotKind,
   type RoutingId,
   type SpotId,
   type SpotRef,
@@ -15,20 +11,26 @@ import {
   type ZLinkSpotCreateCall,
   type ZLinkSpotCreateResult,
   type ZLinkSpotGetOrCreateCall,
-  type ZLinkSpotManager,
-  ZLinkSpotKind
+  type ZLinkSpotManager
 } from '../../contracts';
-import type { ZLinkMessageSerializer } from '../../contracts';
+
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
 import type { ZLinkObjectFactoryRegistration } from '../../contracts/Configuration/RegistrationTypes';
 import { ZLinkConfigurationException } from '../configuration';
-import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
-import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
-import type { DefaultZLinkSpotManager } from './index';
-import { encodeFrameworkCreationPayload } from '../messaging/creation-payload-codec';
-import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
+import { captureZLinkSpotSerialTurn, requireZLinkYieldTurn } from '../execution';
 import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  wireReplyFailureException
+} from '../framework-errors-internal';
+import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
 import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
-import { captureZLinkSpotSerialTurn, requireZLinkYieldTurn } from '../execution';
+import { encodeFrameworkCreationPayload } from '../messaging/creation-payload-codec';
+import type { DefaultZLinkSpotManager } from './index';
+import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
 
 export interface ZLinkPublicSpotManagerOptions {
   readonly local: DefaultZLinkSpotManager;
@@ -100,10 +102,14 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
     if (this.options.isLocalNode(current.meshName, current.nodeRid)) {
       const closed = await this.options.coordinator.close(
         spot,
-        (local) => this.options.local.close(local.meshName, local.spotId, signal),
-        signal,
-        (local) => this.options.local.hasActiveSpot(local.spotId),
-        (local) => this.options.local.canCloseUserSpot(local.meshName, local.spotId)
+        (local, beginAuthority) =>
+          this.options.local.closeUserWithAuthority(
+            local.meshName,
+            local.spotId,
+            beginAuthority,
+            signal
+          ),
+        signal
       );
       if (closed) this.options.resolver()?.invalidate?.(spot.spotId);
       return closed;
@@ -327,8 +333,10 @@ function selectFactory(
 
 function requireText(value: string, label: string): string {
   const bytes = Buffer.byteLength(value);
-  if (bytes < 1 || bytes > 255 || value.includes('\0')) {
-    throw invalidConfiguration(`${label} must contain 1..255 UTF-8 bytes and no NUL.`);
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES || value.includes('\0')) {
+    throw invalidConfiguration(
+      `${label} must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes and no NUL.`
+    );
   }
   return value;
 }

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

@@ -1,3 +1,4 @@
+import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkPeerLocationFilter } from '../../contracts/Locations/Keys';
 import type { ZLinkPeerLocationResolver } from '../../contracts/Locations/Resolvers';
@@ -10,6 +11,7 @@ import type { ZLinkBackendMeshNode } from '../backend/contracts';
 import { AsyncResource } from 'node:async_hooks';
 import { ZLinkStateLane } from '../execution/state-lane';
 import { toBackendRoutingId as toBackendRoutingId } from '../routing-id';
+import { MeshPeerRuntimeState } from '../foundation/service-runtime-contracts';
 import {
   ZLinkLocationRuntime,
   ZLinkOwnerLeaseTracker,
@@ -113,7 +115,7 @@ function meshDescriptorPeerResolver(runtime: ZLinkLocationRuntime): ZLinkPeerLoc
           nodeRid: descriptor.rid,
           role: ZLinkLocationRole.Router,
           endpoint: descriptor.endpoint,
-          weight: 100,
+          weight: ZLINK_DEFAULT_PUBLIC_WEIGHT,
           draining: descriptor.state !== ZLinkFrameworkRuntimeState.Serving,
           value: descriptor.descriptorRevision,
           ownerId: descriptor.ownerId,
@@ -205,7 +207,7 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
           peer.endpoint === target.endpoint &&
           (target.nodeRid === undefined || String(peer.routingId) === String(target.nodeRid)) &&
           peer.lifecycleGeneration === target.lifecycleGeneration &&
-          peer.state === 3
+          peer.state === MeshPeerRuntimeState.Serving
       );
   }
 
@@ -241,7 +243,9 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
   }
 
   private prepareConnectCore(key: string): ZLinkSpotNodeConnectionIntent | undefined {
-    if (this.connectionIntents.has(key)) return undefined;
+    const current = this.connectionIntents.get(key);
+    if (current !== undefined)
+      return current.connectionIntentId === undefined ? current : undefined;
     const intent: ZLinkSpotNodeConnectionIntent = {};
     this.connectionIntents.set(key, intent);
     return intent;
@@ -252,29 +256,19 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
     key: string,
     intent: ZLinkSpotNodeConnectionIntent
   ): Promise<boolean> {
-    try {
-      const connectionIntentId = await this.node.connectPeer({
-        endpoint: target.endpoint,
-        expectedRid: target.nodeRid === undefined ? undefined : toBackendRoutingId(target.nodeRid),
-        expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
-        expectedLifecycleGeneration: target.lifecycleGeneration
-      });
-      const accepted = await this.lane.run(() => {
-        if (this.connectionIntents.get(key) !== intent) return false;
-        intent.connectionIntentId = connectionIntentId;
-        return true;
-      });
-      if (!accepted) this.node.removePeerConnection(connectionIntentId);
-      return accepted;
-    } catch {
-      // A discovered endpoint can become unavailable between the store read and
-      // the socket connect. Leave the target inactive so the next reconciliation
-      // can retry without terminating the host's background runtime.
-      await this.lane.run(() => {
-        if (this.connectionIntents.get(key) === intent) this.connectionIntents.delete(key);
-      });
-      return false;
-    }
+    const connectionIntentId = await this.node.connectPeer({
+      endpoint: target.endpoint,
+      expectedRid: target.nodeRid === undefined ? undefined : toBackendRoutingId(target.nodeRid),
+      expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
+      expectedLifecycleGeneration: target.lifecycleGeneration
+    });
+    const accepted = await this.lane.run(() => {
+      if (this.connectionIntents.get(key) !== intent) return false;
+      intent.connectionIntentId = connectionIntentId;
+      return true;
+    });
+    if (!accepted) this.node.removePeerConnection(connectionIntentId);
+    return accepted;
   }
 
   private disconnectPeer(target: ZLinkAutoConnectTarget): void {