@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkPeerLocationFilter } from '../../contracts/Locations/Keys';
@@ -8,13 +9,13 @@ import { ZLinkLocationAutoConnectType } from '../../contracts/Locations/Values';
 import { ZLinkFrameworkRuntimeState, ZLinkLocationRole } from '../../contracts';
 import type { ZLinkSpotNodeOptions } from '../configuration';
 import type { ZLinkBackendMeshNode } from '../backend/contracts';
-import { AsyncResource } from 'node:async_hooks';
-import { ZLinkStateLane } from '../execution/state-lane';
+import { startOutsideStateLane, ZLinkStateLane } from '../execution/state-lane';
 import { toBackendRoutingId as toBackendRoutingId } from '../routing-id';
 import { MeshPeerRuntimeState } from '../foundation/service-runtime-contracts';
 import {
   ZLinkLocationRuntime,
   ZLinkOwnerLeaseTracker,
+  ZLinkRequestSourceResolver,
   type IZLinkAutoConnectExecutor,
   type ZLinkAutoConnectLocal,
   type ZLinkAutoConnectTarget,
@@ -28,6 +29,7 @@ export interface ZLinkSpotNodeLocationAutoConnectContext {
   readonly options: ZLinkLocationOptionOverrides;
   readonly leaseTracker: ZLinkOwnerLeaseTracker;
   readonly resolver: ZLinkPeerLocationResolver;
+  readonly requestSources: ZLinkRequestSourceResolver;
   readonly events?: ZLinkLocationEventSink;
   readonly changeStampStore?: Pick<ZLinkLocationStore, 'getMeshNodeChangeStamp'>;
 }
@@ -48,12 +50,17 @@ export function createSpotNodeLocationAutoConnectContext(
     store: stores.ownerLeaseStore,
     options
   });
+  const requestSources = new ZLinkRequestSourceResolver({
+    listLiveMeshNodes: (meshName, signal) => runtime.listLiveMeshNodes(meshName, signal),
+    remainingOwnerTokenLeaseMs: (owner, signal) => runtime.remainingOwnerTokenLeaseMs(owner, signal)
+  });
   return {
     runtime,
     stores,
     options,
     leaseTracker,
-    resolver: meshDescriptorPeerResolver(runtime),
+    resolver: meshDescriptorPeerResolver(runtime, requestSources),
+    requestSources,
     events,
     // The opaque provider has no cross-process change notification primitive.
     // A process-local inherited stamp would hide descriptors written by peers,
@@ -86,14 +93,16 @@ export function spotNodeAutoConnectCapability(
       (channel) => channel.server === true
     )
   };
-  const manualConnections = hasManualRouterConnections(spotNode);
   return {
     local,
-    executor: new ZLinkSpotNodeAutoConnectExecutor(node, manualConnections)
+    executor: new ZLinkSpotNodeAutoConnectExecutor(node)
   };
 }
 
-function meshDescriptorPeerResolver(runtime: ZLinkLocationRuntime): ZLinkPeerLocationResolver {
+function meshDescriptorPeerResolver(
+  runtime: ZLinkLocationRuntime,
+  requestSources: ZLinkRequestSourceResolver
+): ZLinkPeerLocationResolver {
   return {
     async listLivePeers(
       filter: ZLinkPeerLocationFilter,
@@ -108,6 +117,8 @@ function meshDescriptorPeerResolver(runtime: ZLinkLocationRuntime): ZLinkPeerLoc
         return [];
       }
       const descriptors = await runtime.listLiveMeshNodes(filter.meshName, signal);
+      // The auto-connect poll owns the live descriptors; request acceptance reads them.
+      await requestSources.observeLiveDescriptors(filter.meshName, descriptors, signal);
       return descriptors
         .map((descriptor): ZLinkPeerLocation => ({
           autoConnectType: ZLinkLocationAutoConnectType.RouteMesh,
@@ -130,22 +141,13 @@ function meshDescriptorPeerResolver(runtime: ZLinkLocationRuntime): ZLinkPeerLoc
         }))
         .filter(
           (peer) =>
-            (filter.nodeRid === undefined || String(peer.nodeRid) === String(filter.nodeRid)) &&
+            (filter.nodeRid === undefined || routingIdsEqual(peer.nodeRid, filter.nodeRid)) &&
             (filter.endpoint === undefined || peer.endpoint === filter.endpoint)
         );
     }
   };
 }
 
-function hasManualRouterConnections(spotNode: ZLinkSpotNodeOptions): boolean {
-  return (
-    (spotNode.router?.manualConnections?.length ?? 0) > 0 ||
-    (spotNode.router?.manualPeerConnections?.length ?? 0) > 0
-  );
-}
-
-const detachedSpotNodeAutoConnectResource = new AsyncResource('zlink:spot-node-autoconnect');
-
 interface ZLinkSpotNodeConnectionIntent {
   connectionIntentId?: bigint;
 }
@@ -154,46 +156,29 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
   private readonly lane = new ZLinkStateLane();
   private readonly connectionIntents = new Map<string, ZLinkSpotNodeConnectionIntent>();
 
-  constructor(
-    private readonly node: ZLinkBackendMeshNode,
-    private readonly manualConnections: boolean
-  ) {}
+  constructor(private readonly node: ZLinkBackendMeshNode) {}
 
   onDisconnected(handler: (endpoint: string) => void): void {
     this.node.onPeerDisconnected?.(handler);
   }
 
   async connect(target: ZLinkAutoConnectTarget): Promise<boolean> {
-    if (this.manualConnections) return false;
     const key = connectionKey(target);
+    if (
+      !this.connectionIntents.has(key) &&
+      this.node.hasPeerRouteOrConnectionIntent?.(target.nodeRid, target.endpoint) === true
+    )
+      return false;
     const intent = await this.lane.run(() => this.prepareConnectCore(key));
     if (intent === undefined) return true;
-    return await runDetachedSpotNodeAutoConnect(() => this.connectPeer(target, key, intent));
+    return await startOutsideStateLane(() => this.connectPeer(target, key, intent));
   }
 
   disconnect(target: ZLinkAutoConnectTarget): void {
-    if (this.manualConnections) return;
+    if (!this.connectionIntents.has(connectionKey(target))) return;
     this.disconnectPeer(target);
   }
 
-  disconnectStalePeers(targets: readonly ZLinkAutoConnectTarget[]): void {
-    if (this.manualConnections) return;
-    const current = new Map(
-      targets
-        .filter((target) => target.nodeRid !== undefined)
-        .map((target) => [String(target.nodeRid), target])
-    );
-    const peers = this.node.peers();
-    for (const peer of peers) {
-      if (peer.routingId === null) continue;
-      const target = current.get(String(peer.routingId));
-      if (target !== undefined && peer.endpoint === target.endpoint) {
-        continue;
-      }
-      this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
-    }
-  }
-
   isDisconnected(target: ZLinkAutoConnectTarget): boolean {
     // A connect intent still owns transport state even when its peer has not
     // reached the admitted table yet. Shutdown must remove that intent before
@@ -205,7 +190,7 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
         (peer) =>
           peer.routingId !== null &&
           peer.endpoint === target.endpoint &&
-          (target.nodeRid === undefined || String(peer.routingId) === String(target.nodeRid)) &&
+          (target.nodeRid === undefined || routingIdsEqual(peer.routingId, target.nodeRid)) &&
           peer.lifecycleGeneration === target.lifecycleGeneration &&
           peer.state === MeshPeerRuntimeState.Serving
       );
@@ -287,7 +272,7 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
       if (peer.endpoint !== target.endpoint) {
         continue;
       }
-      if (target.nodeRid !== undefined && String(peer.routingId) !== String(target.nodeRid)) {
+      if (target.nodeRid !== undefined && !routingIdsEqual(peer.routingId, target.nodeRid)) {
         continue;
       }
       this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
@@ -295,10 +280,6 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
   }
 }
 
-function runDetachedSpotNodeAutoConnect<T>(work: () => Promise<T>): Promise<T> {
-  return detachedSpotNodeAutoConnectResource.runInAsyncScope(work);
-}
-
 function connectionKey(target: ZLinkAutoConnectTarget): string {
   return `${target.nodeRid ?? ''}\0${target.lifecycleGeneration}\0${target.endpoint}`;
 }

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

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { RuntimeDisposal } from '../disposal';
 import { randomUUID } from 'node:crypto';
@@ -34,7 +35,7 @@ import {
 import { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from '../../contracts/Locations';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkLocationOwnerToken } from '../../contracts/Locations/Writes';
-import { createAbortError } from '../abort';
+import { awaitWithAbort, createAbortError } from '../abort';
 import type { ZLinkActivationConcurrency } from '../activation-admission';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
@@ -205,6 +206,12 @@ export class ZLinkSpotNodeRuntimeManager {
     );
   }
 
+  async requestPeerReconcile(meshName: string, peerRid: string): Promise<void> {
+    await Promise.all(
+      this.autoConnectLoops.map((loop) => loop.requestPeerReconcile(meshName, peerRid))
+    );
+  }
+
   async startLocationAutoConnect(signal?: AbortSignal): Promise<void> {
     const location = this.locationAutoConnect;
     if (location === undefined || this.autoConnectLoops.length > 0) {
@@ -218,6 +225,16 @@ export class ZLinkSpotNodeRuntimeManager {
         }
         const capability = spotNodeAutoConnectCapability(spotNodeName, spotNode, node);
         if (capability === undefined) continue;
+        node.setRequestSourceAcceptance?.(
+          (nodeRid, nodeGeneration, nodeRidStorageHex, sourceSignal) =>
+            location.requestSources.accept(
+              capability.local.meshName,
+              nodeRid,
+              nodeGeneration,
+              nodeRidStorageHex,
+              sourceSignal
+            )
+        );
         const reconciler = new ZLinkAutoConnectReconciler({
           local: capability.local,
           localRow: capability.localRow,
@@ -292,6 +309,24 @@ export class ZLinkSpotNodeRuntimeManager {
       if (this.options.dispatchErrors !== undefined) {
         node.setDispatchErrorReporter?.(this.options.dispatchErrors, spotNodeName);
       }
+      // Session-Actor binding §4: the Session owner identity comes from the
+      // host's own descriptor or from a peer descriptor that passed the
+      // Location runtime §4.1 owner lease check.
+      node.setSessionOwnerDescriptors?.({
+        local: () => this.locationAutoConnect?.runtime.currentOwnerToken,
+        peer: async (peerRid, peerGeneration) => {
+          const location = this.locationAutoConnect;
+          if (location === undefined) return undefined;
+          const descriptor = (await location.runtime.listLiveMeshNodes(spotNodeName)).find(
+            (candidate) =>
+              routingIdsEqual(candidate.rid, peerRid) &&
+              candidate.lifecycleGeneration === peerGeneration
+          );
+          return descriptor === undefined
+            ? undefined
+            : { ownerId: descriptor.ownerId, leaseGeneration: descriptor.leaseGeneration };
+        }
+      });
       node.setMailboxRecordDroppedHandler?.((record) =>
         this.options.dispatchErrors?.report({
           surface: ZLinkDispatchErrorSurface.RouteMeshChannel,
@@ -412,7 +447,7 @@ export class ZLinkSpotNodeRuntimeManager {
         this.meshNodes.delete(spotNodeName);
         completions.dispose(error);
         await pump?.dispose();
-        node.close();
+        await node.close();
         throw error;
       }
     }
@@ -447,9 +482,8 @@ export class ZLinkSpotNodeRuntimeManager {
     const ownerChanged =
       this.publishedOwnerToken !== undefined && !sameOwnerToken(this.publishedOwnerToken, owner);
     if (ownerChanged) {
-      // A new owner token can refer to an empty or replaced Store. The cached
-      // descriptor was written under the previous lease and must not force a
-      // Renew against a row that no longer exists.
+      // A descriptor confirmed under the previous lease must not supply
+      // cached population data for a new owner token.
       this.publishedMeshNodeDescriptors.clear();
     }
     for (const [meshName, registration] of this.options.registration.spotNodes) {
@@ -467,7 +501,14 @@ export class ZLinkSpotNodeRuntimeManager {
         ...instanceSpots.map(([stableType, factory]) =>
           objectCapability('instance_spot', stableType, factory)
         ),
-        ...actors.map(([stableType, factory]) => objectCapability('actor', stableType, factory))
+        ...actors.map(([stableType, factory]) =>
+          objectCapability(
+            'actor',
+            stableType,
+            factory,
+            registrationAcceptsNewActor(registration, stableType)
+          )
+        )
       ].sort((left, right) => {
         const kindOrder = left.objectKind.localeCompare(right.objectKind);
         return kindOrder !== 0 ? kindOrder : left.stableType.localeCompare(right.stableType);
@@ -482,9 +523,8 @@ export class ZLinkSpotNodeRuntimeManager {
         // The raw MeshNode resolves port zero and applies AdvertiseHost once.
         // Discovery and RouteMesh hello must publish that same public identity.
         endpoint: status.localEndpoint,
-        objectRole: effectiveObjectRole(registration),
+        ...this.localDescriptorFields(meshName, registration, state),
         entrySpotId: this.entrySpotId(meshName, registration),
-        placementWeight: this.placementWeight(meshName),
         populationCapacity: {
           actors: {
             active: current?.populationCapacity.actors.active ?? 0,
@@ -517,19 +557,6 @@ export class ZLinkSpotNodeRuntimeManager {
           active: 0,
           limit: registration.activationConcurrencyLimit ?? DEFAULT_ACTIVATION_CONCURRENCY_LIMIT
         },
-        channelWeights: Object.fromEntries(
-          this.serverChannels(meshName).map(([channelName, channel]) => [
-            channelName,
-            state === ZLinkFrameworkRuntimeState.Draining
-              ? 0
-              : this.effectiveChannelWeight(
-                  meshName,
-                  channelName,
-                  channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
-                )
-          ])
-        ),
-        applicationVersion: this.options.registration.applicationVersion,
         maintenanceWave: this.options.registration.maintenanceWave,
         spotTypes: [
           ...userSpots.map(([stableType]) => stableType),
@@ -540,13 +567,14 @@ export class ZLinkSpotNodeRuntimeManager {
         state,
         securityIdentity: 'default'
       };
+      // Revision is issued before submission: an unconfirmed Store write may
+      // already have applied, so the next publication must not reuse it.
+      this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
       const result = await location.runtime.writeMeshNode(
         descriptor,
-        ownerChanged
-          ? ZLinkLocationWriteIntent.Renew
-          : current === undefined
-            ? ZLinkLocationWriteIntent.NewClaim
-            : ZLinkLocationWriteIntent.Renew,
+        previousRevision === 0n
+          ? ZLinkLocationWriteIntent.NewClaim
+          : ZLinkLocationWriteIntent.Renew,
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -560,11 +588,37 @@ export class ZLinkSpotNodeRuntimeManager {
         leaseGeneration: location.runtime.currentOwnerToken!.leaseGeneration,
         updatedAt: result.updatedAt
       });
-      this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
     }
     this.publishedOwnerToken = owner;
   }
 
+  private localDescriptorFields(
+    meshName: string,
+    registration: ZLinkSpotNodeOptions,
+    state: ZLinkFrameworkRuntimeState
+  ): Pick<
+    ZLinkMeshNodeDescriptor,
+    'objectRole' | 'placementWeight' | 'channelWeights' | 'applicationVersion'
+  > {
+    return {
+      objectRole: effectiveObjectRole(registration),
+      placementWeight: this.placementWeight(meshName),
+      channelWeights: Object.fromEntries(
+        this.serverChannels(meshName).map(([channelName, channel]) => [
+          channelName,
+          state === ZLinkFrameworkRuntimeState.Draining
+            ? 0
+            : this.effectiveChannelWeight(
+                meshName,
+                channelName,
+                channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
+              )
+        ])
+      ),
+      applicationVersion: this.options.registration.applicationVersion
+    };
+  }
+
   async reconcileAndPublishMeshNodeState(
     state: ZLinkFrameworkRuntimeState,
     meshName: string,
@@ -578,13 +632,20 @@ export class ZLinkSpotNodeRuntimeManager {
     if (owner === undefined) return;
     const current = (await location.runtime.listLiveMeshNodes(meshName, signal)).find(
       (descriptor) =>
-        String(descriptor.rid) === String(status.routingId) &&
+        routingIdsEqual(descriptor.rid, status.routingId) &&
         descriptor.lifecycleGeneration === status.lifecycleGeneration &&
         descriptor.ownerId === owner.ownerId &&
         descriptor.leaseGeneration === owner.leaseGeneration
     );
     if (current !== undefined) {
-      this.publishedMeshNodeDescriptors.set(meshName, current);
+      this.publishedMeshNodeDescriptors.set(meshName, {
+        ...current,
+        ...this.localDescriptorFields(
+          meshName,
+          this.options.registration.spotNodes.get(meshName)!,
+          state
+        )
+      });
       this.descriptorRevisionByMesh.set(
         meshName,
         maxBigInt(this.descriptorRevisionByMesh.get(meshName) ?? 0n, current.descriptorRevision)
@@ -848,12 +909,16 @@ export class ZLinkSpotNodeRuntimeManager {
     };
     await settle(publishers.map(async (publisher) => publisher.close()));
     await settle(autoConnectLoops.map((loop) => loop.prepareTransportShutdown()));
-    await settle(entryActivations.reverse().map((activation) => activation.dispose(deadline)));
-    await settle(meshPumps.reverse().map((pump) => pump.dispose()));
+    await settle(
+      entryActivations
+        .reverse()
+        .map((activation) => awaitWithAbort(activation.dispose(deadline), signal))
+    );
+    await settle(meshPumps.reverse().map((pump) => pump.dispose(signal)));
     await settle(
       meshNodes.reverse().map(async (node) => {
-        node.shutdown(DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS);
-        node.close();
+        await node.shutdown(DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS);
+        await node.close();
       })
     );
     for (const completions of meshCompletions) {
@@ -870,39 +935,61 @@ export class ZLinkSpotNodeRuntimeManager {
     this.meshCompletions.clear();
   }
 
-  private async dispatchMeshRecord(
+  /**
+   * Node and Channel records go straight to the framework dispatcher in the
+   * pump's turn. Only Spot and Actor records addressed to the Entry Spot wait
+   * for its activation first.
+   */
+  private dispatchMeshRecord(
     meshName: string,
     owner: ReadyRecord,
     record: ReceiveRecord
-  ): Promise<void> {
-    const node = this.meshNodes.get(meshName);
-    const targetsEntrySpot =
-      owner.spotId === null ||
-      (node !== undefined &&
-        routingIdsEqual(owner.spotId as unknown as RoutingId, String(node.status().routingId)));
+  ): void | Promise<void> {
     if (
-      targetsEntrySpot &&
       (record.kind === ReceiveKind.ActorSend ||
         record.kind === ReceiveKind.ActorRequest ||
         record.kind === ReceiveKind.SpotSend ||
         record.kind === ReceiveKind.SpotRequest ||
-        record.kind === ReceiveKind.SpotMulticast)
+        record.kind === ReceiveKind.SpotMulticast) &&
+      this.targetsEntrySpot(meshName, owner)
     ) {
-      await this.ensureEntryActivation(meshName);
+      return this.ensureEntryActivation(meshName).then(() =>
+        this.dispatchFrameworkRecord(meshName, owner, record)
+      );
     }
+    return this.dispatchFrameworkRecord(meshName, owner, record);
+  }
+
+  private targetsEntrySpot(meshName: string, owner: ReadyRecord): boolean {
+    if (owner.spotId === null) return true;
+    const node = this.meshNodes.get(meshName);
+    return (
+      node !== undefined &&
+      routingIdsEqual(owner.spotId as unknown as RoutingId, String(node.status().routingId))
+    );
+  }
+
+  private dispatchFrameworkRecord(
+    meshName: string,
+    owner: ReadyRecord,
+    record: ReceiveRecord
+  ): void | Promise<void> {
     const dispatcher = this.options.meshRecordDispatcher;
     if (dispatcher === undefined) {
-      throw new ZLinkConfigurationException(
-        `MeshNode '${meshName}' received a record before its framework dispatcher was registered.`
+      return Promise.reject(
+        new ZLinkConfigurationException(
+          `MeshNode '${meshName}' received a record before its framework dispatcher was registered.`
+        )
       );
     }
-    await dispatcher(meshName, owner, record);
+    return dispatcher(meshName, owner, record);
   }
 
   async dispatchEntrySpotRecord(
     meshName: string,
     owner: ReadyRecord,
-    record: ReceiveRecord
+    record: ReceiveRecord,
+    admit?: ZLinkMeshDispatchAdmission
   ): Promise<boolean> {
     if (
       record.kind !== ReceiveKind.SpotSend &&
@@ -922,11 +1009,13 @@ export class ZLinkSpotNodeRuntimeManager {
           'MeshNode Entry Spot multicast record is missing its topic.'
         );
       }
-      await activation.dispatchSubscriptionRecord(
-        record.topic,
-        record.parts,
-        record.sourceNodeRid as unknown as RoutingId | null
-      );
+      const dispatch = () =>
+        activation.dispatchSubscriptionRecord(
+          record.topic!,
+          record.parts,
+          record.sourceNodeRid as unknown as RoutingId | null
+        );
+      await (admit === undefined ? dispatch() : admit(dispatch));
       return true;
     }
     const envelope = decodeChannelEnvelope(
@@ -940,21 +1029,30 @@ export class ZLinkSpotNodeRuntimeManager {
       channelName: envelope.header.channelName,
       contentType: envelope.header.contentType
     };
-    if (record.kind === ReceiveKind.SpotSend) {
-      await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, false);
-      return true;
-    }
     try {
-      const response = await activation.dispatchPacketEncoded(
-        envelope.packetName,
-        decodePayload,
-        context,
-        true
-      );
-      requireEntrySpotReply(
-        record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
-      );
+      const dispatch = async () => {
+        if (record.kind === ReceiveKind.SpotSend) {
+          await activation.dispatchPacketEncoded(
+            envelope.packetName,
+            decodePayload,
+            context,
+            false
+          );
+          return;
+        }
+        const response = await activation.dispatchPacketEncoded(
+          envelope.packetName,
+          decodePayload,
+          context,
+          true
+        );
+        requireEntrySpotReply(
+          record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
+        );
+      };
+      await (admit === undefined ? dispatch() : admit(dispatch));
     } catch (error) {
+      if (record.kind !== ReceiveKind.SpotRequest) throw error;
       requireEntrySpotReply(record.reply(encodeChannelErrorReplyParts(envelope.header, error)));
     }
     return true;
@@ -1110,6 +1208,20 @@ export class ZLinkSpotNodeRuntimeManager {
     await activation.commitServiceActorJoin(actor, handoffBacklog);
   }
 
+  admitEntryActorPacketPrefix(
+    meshName: string,
+    actorId: string,
+    records: readonly import('../actors/actor-handoff').ZLinkActorHandoffPrefixRecord[]
+  ): import('../actors/actor-handoff').ZLinkActorHandoffPrefixAdmission {
+    const activation = this.entryActivations.get(meshName);
+    if (activation === undefined) {
+      throw new ZLinkConfigurationException(
+        `Entry Spot Actor '${actorId}' has no activation for MeshNode '${meshName}'.`
+      );
+    }
+    return activation.admitActorPacketPrefix(actorId, records);
+  }
+
   executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T> {
     const activation = this.entryActivations.get(meshName);
     if (activation === undefined) {
@@ -1345,7 +1457,8 @@ function effectiveObjectRole(registration: ZLinkSpotNodeOptions): ZLinkObjectRol
 function objectCapability(
   objectKind: 'actor' | 'user_spot' | 'instance_spot',
   stableType: string,
-  factory: DescriptorFactoryRegistration
+  factory: DescriptorFactoryRegistration,
+  entryAccepted = false
 ) {
   const policy = factory.relocation?.kind ?? 'disabled';
   return {
@@ -1353,10 +1466,27 @@ function objectCapability(
     stableType,
     policy,
     hasSnapshotAdapter: policy === 'snapshot',
-    limit: objectKind === 'actor' ? 0 : (factory.options?.stableTypeLimit ?? 0)
+    limit: objectKind === 'actor' ? 0 : (factory.options?.stableTypeLimit ?? 0),
+    entryAccepted
   };
 }
 
+/**
+ * The one decision for creating a new Actor on this node (Actor model §6.3): the node registered
+ * an Entry Spot type that accepts the Actor type and an Actor factory for it. Publication and the
+ * target refusal both read it.
+ */
+export function registrationAcceptsNewActor(
+  registration: ZLinkSpotNodeOptions,
+  stableType: string
+): boolean {
+  return (
+    registration.entrySpotType !== undefined &&
+    registration.entrySpotActorType === stableType &&
+    effectiveActorRegistrations(registration).some(([type]) => type === stableType)
+  );
+}
+
 function aggregatePlacementCapacity(actorLimit: number, spotLimit: number): number {
   const unlimited = ZLINK_MAX_CAPACITY;
   const actors = actorLimit === 0 ? unlimited : actorLimit;