@zlink-systems/framework 0.24.0 → 0.26.0

package/src/runtime/foundation/service-stateful-wire-codec.ts

@@ -19,6 +19,19 @@ import {
   encodeCanonicalServiceWireText,
   encodeServiceWireRoutingId
 } from './service-wire-binary-primitives';
+import {
+  decodeActorRequestCommand,
+  decodeActorSendCommand,
+  decodeMetadataFrame,
+  decodeSpotRequestCommand,
+  decodeSpotSendCommand,
+  encodeActorRequestCommand,
+  encodeActorSendCommand,
+  encodeApplicationPayloadEnvelopeV1,
+  encodeSpotRequestCommand,
+  encodeSpotSendCommand,
+  type ServiceWireDecoderContext
+} from '../protocol/service_wire_codec.generated';
 import {
   decodeActorCreate49 as decodeGeneratedActorCreate49,
   decodeActorJoin28,
@@ -337,6 +350,7 @@ export type ServiceSessionRelocationRoute =
         readonly targetAuthorityOwnerGeneration: bigint;
         readonly targetNodeRid: string;
         readonly targetNodeGeneration: bigint;
+        readonly targetOwnerLeaseGeneration: bigint;
       };
     }
   | {
@@ -1015,8 +1029,10 @@ export type ServiceStatefulWireRecord =
   | {
       readonly kind: 'spotSend' | 'spotRequest';
       readonly correlation?: bigint;
+      readonly operation: ServiceWireOperationId;
+      readonly messageFollowHopCount: number;
       readonly sourceSpotId: string;
-      readonly target: ServiceDirectSpotRouteFence;
+      readonly target: ServiceSpotRouteFence;
     }
   | {
       readonly kind: 'logicalMulticast';
@@ -1027,6 +1043,8 @@ export type ServiceStatefulWireRecord =
   | {
       readonly kind: 'actorSend' | 'actorRequest';
       readonly correlation?: bigint;
+      readonly operation: ServiceWireOperationId;
+      readonly messageFollowHopCount: number;
       readonly sourceActor?: ServiceActorRef;
       readonly target: ServiceActorRouteFence;
       readonly boundSession?: ServiceBoundSessionSource;
@@ -1137,20 +1155,68 @@ export interface ServiceStatefulReply {
   readonly tail?: ServiceStatefulReplyTail;
 }
 
+const STATEFUL_MESSAGE_CONTEXT: ServiceWireDecoderContext = {
+  effectiveCompleteMessageBytesMinusActualEnvelopeOverhead: 0xffff_fdf6,
+  effectiveCompleteMessageBytes: 0xffff_ffff
+};
+const STATEFUL_HEADER_PAYLOAD = {
+  packetName: 'wire',
+  contentType: 'application/json',
+  payload: Buffer.from('{}')
+};
+
+function generatedSpotFence(target: ServiceSpotRouteFence) {
+  return {
+    spot: { spotId: target.spot.spotId, objectGeneration: target.spot.generation },
+    targetNodeRid: toGeneratedRoutingId(target.targetNodeRid, 'targetNodeRid'),
+    targetNodeGeneration: target.targetNodeGeneration,
+    expectedAuthorityOwnerGeneration: target.authorityOwnerGeneration,
+    expectedOwnerLeaseGeneration: target.ownerLeaseGeneration
+  };
+}
+
+function generatedActorFence(target: ServiceActorRouteFence) {
+  return {
+    actor: { actorId: target.actor.actorId, objectGeneration: target.actor.generation },
+    targetNodeRid: toGeneratedRoutingId(target.actor.nodeRid, 'targetNodeRid'),
+    targetNodeGeneration: target.targetNodeGeneration,
+    expectedAuthorityOwnerGeneration: target.authorityOwnerGeneration,
+    expectedOwnerLeaseGeneration: target.ownerLeaseGeneration
+  };
+}
+
 export function encodeSpotHeader(
   kind: 'spotSend' | 'spotRequest',
   sourceSpotId: string,
   target: ServiceDirectSpotRouteFence,
-  correlation?: bigint
+  correlation?: bigint,
+  operation: ServiceWireOperationId = { high: 0n, low: 1n },
+  messageFollowHopCount = 0,
+  metadataFrame?: Uint8Array
 ): Buffer {
-  return concat(
-    prefix(
-      kind === 'spotSend' ? M6bServiceWireCommand.spotSend : M6bServiceWireCommand.spotRequest
-    ),
-    ...(kind === 'spotRequest' ? [u64(requirePositive(correlation, 'correlation'))] : []),
-    rid(sourceSpotId, 'sourceSpotId'),
-    directSpotFence(target)
-  );
+  const common = {
+    flags: metadataFrame === undefined ? 0 : M6bServiceWireFlag.metadata,
+    operation,
+    messageFollowHopCount,
+    sourceSpotId,
+    targetSpot: generatedSpotFence(target),
+    payload: STATEFUL_HEADER_PAYLOAD,
+    ...(metadataFrame === undefined
+      ? {}
+      : { metadata: decodeMetadataFrame(metadataFrame, STATEFUL_MESSAGE_CONTEXT) })
+  };
+  const frames =
+    kind === 'spotSend'
+      ? encodeSpotSendCommand({ command: kind, ...common }, STATEFUL_MESSAGE_CONTEXT)
+      : encodeSpotRequestCommand(
+          {
+            command: kind,
+            ...common,
+            correlation: requirePositive(correlation, 'correlation')
+          },
+          STATEFUL_MESSAGE_CONTEXT
+        );
+  return Buffer.from(frames[0]!);
 }
 
 export function encodeActorHeader(
@@ -1158,28 +1224,46 @@ export function encodeActorHeader(
   target: ServiceActorRouteFence,
   correlation?: bigint,
   sourceActor?: ServiceActorRef,
-  boundSession?: ServiceBoundSessionSource
+  boundSession?: ServiceBoundSessionSource,
+  operation: ServiceWireOperationId = { high: 0n, low: 1n },
+  messageFollowHopCount = 0
 ): Buffer {
   const flags =
     boundSession === undefined
       ? 0
       : M6bServiceWireFlag.boundSession | M6bServiceWireFlag.sourceSpotId;
-  return concat(
-    prefix(
-      kind === 'actorSend' ? M6bServiceWireCommand.actorSend : M6bServiceWireCommand.actorRequest,
-      flags
-    ),
-    ...(kind === 'actorRequest' ? [u64(requirePositive(correlation, 'correlation'))] : []),
-    optionalActor(sourceActor),
-    actorFence(target),
+  const common = {
+    flags,
+    operation,
+    messageFollowHopCount,
+    sourceActor:
+      sourceActor === undefined
+        ? { actorId: null }
+        : { actorId: sourceActor.actorId, generation: sourceActor.generation },
+    targetActor: generatedActorFence(target),
     ...(boundSession === undefined
-      ? []
-      : [
-          rid(boundSession.sessionRid, 'sourceSessionRid'),
-          u64(boundSession.bindingGeneration),
-          u64(boundSession.sequence)
-        ])
-  );
+      ? {}
+      : {
+          boundSessionTail: {
+            sourceSessionRid: toGeneratedRoutingId(boundSession.sessionRid, 'sourceSessionRid'),
+            sourceBindingGeneration: boundSession.bindingGeneration,
+            sourceSessionSequence: boundSession.sequence
+          }
+        }),
+    payload: STATEFUL_HEADER_PAYLOAD
+  };
+  const frames =
+    kind === 'actorSend'
+      ? encodeActorSendCommand({ command: kind, ...common }, STATEFUL_MESSAGE_CONTEXT)
+      : encodeActorRequestCommand(
+          {
+            command: kind,
+            ...common,
+            correlation: requirePositive(correlation, 'correlation')
+          },
+          STATEFUL_MESSAGE_CONTEXT
+        );
+  return Buffer.from(frames[0]!);
 }
 
 export function encodeLogicalMulticastHeader(
@@ -1420,7 +1504,11 @@ export function encodeMessageFollowHeader(
   );
 }
 
-export function decodeStatefulHeader(frame: Uint8Array): ServiceStatefulWireRecord {
+export function decodeStatefulHeader(
+  frame: Uint8Array,
+  payloadFrame?: Uint8Array,
+  metadataFrame?: Uint8Array
+): ServiceStatefulWireRecord {
   switch (frame[3]) {
     case M6bServiceWireCommand.userSpotCreate:
       return fromGeneratedUserSpotCreate(decodeGeneratedUserSpotCreate47(frame));
@@ -1428,52 +1516,98 @@ export function decodeStatefulHeader(frame: Uint8Array): ServiceStatefulWireReco
       return fromGeneratedUserSpotClose(decodeGeneratedUserSpotClose48(frame));
     case M6bServiceWireCommand.actorCreate:
       return fromGeneratedActorCreate(decodeGeneratedActorCreate49(frame));
-  }
-  const reader = new Reader(frame);
-  const command = reader.prefix();
-  switch (command.command) {
     case M6bServiceWireCommand.spotSend:
-    case M6bServiceWireCommand.spotRequest: {
-      requireFlags(command.flags, 0);
-      const request = command.command === M6bServiceWireCommand.spotRequest;
-      const correlation = request ? reader.nonZeroU64('correlation') : undefined;
-      const sourceSpotId = reader.rid('sourceSpotId');
-      const target = reader.directSpotFence();
-      reader.end();
-      return {
-        kind: request ? 'spotRequest' : 'spotSend',
-        ...(correlation === undefined ? {} : { correlation }),
-        sourceSpotId,
-        target
-      };
-    }
+    case M6bServiceWireCommand.spotRequest:
     case M6bServiceWireCommand.actorSend:
     case M6bServiceWireCommand.actorRequest: {
-      const request = command.command === M6bServiceWireCommand.actorRequest;
-      const hasBinding = command.flags !== 0;
-      requireFlags(
-        command.flags,
-        hasBinding ? M6bServiceWireFlag.boundSession | M6bServiceWireFlag.sourceSpotId : 0
-      );
-      const correlation = request ? reader.nonZeroU64('correlation') : undefined;
-      const sourceActor = reader.optionalActor();
-      const target = reader.actorFence();
-      const boundSession = hasBinding
-        ? {
-            sessionRid: reader.rid('sourceSessionRid'),
-            bindingGeneration: reader.nonZeroU64('sourceBindingGeneration'),
-            sequence: reader.nonZeroU64('sourceSessionSequence')
-          }
-        : undefined;
-      reader.end();
-      return {
-        kind: request ? 'actorRequest' : 'actorSend',
-        ...(correlation === undefined ? {} : { correlation }),
-        ...(sourceActor === undefined ? {} : { sourceActor }),
-        target,
-        ...(boundSession === undefined ? {} : { boundSession })
-      };
+      const frames = [
+        frame,
+        ...(metadataFrame === undefined ? [] : [metadataFrame]),
+        payloadFrame ??
+          encodeApplicationPayloadEnvelopeV1(STATEFUL_HEADER_PAYLOAD, STATEFUL_MESSAGE_CONTEXT)
+      ];
+      try {
+        if (
+          frame[3] === M6bServiceWireCommand.spotSend ||
+          frame[3] === M6bServiceWireCommand.spotRequest
+        ) {
+          const decoded =
+            frame[3] === M6bServiceWireCommand.spotSend
+              ? decodeSpotSendCommand(frames, STATEFUL_MESSAGE_CONTEXT)
+              : decodeSpotRequestCommand(frames, STATEFUL_MESSAGE_CONTEXT);
+          return {
+            kind: decoded.command,
+            ...(decoded.command === 'spotRequest' ? { correlation: decoded.correlation } : {}),
+            operation: decoded.operation,
+            messageFollowHopCount: decoded.messageFollowHopCount,
+            sourceSpotId: decoded.sourceSpotId,
+            target: {
+              spot: {
+                spotId: decoded.targetSpot.spot.spotId,
+                generation: decoded.targetSpot.spot.objectGeneration
+              },
+              targetNodeRid: fromGeneratedRoutingId(
+                decoded.targetSpot.targetNodeRid,
+                'targetNodeRid'
+              ),
+              targetNodeGeneration: decoded.targetSpot.targetNodeGeneration,
+              authorityOwnerGeneration: decoded.targetSpot.expectedAuthorityOwnerGeneration,
+              ownerLeaseGeneration: decoded.targetSpot.expectedOwnerLeaseGeneration
+            }
+          };
+        }
+        const decoded =
+          frame[3] === M6bServiceWireCommand.actorSend
+            ? decodeActorSendCommand(frames, STATEFUL_MESSAGE_CONTEXT)
+            : decodeActorRequestCommand(frames, STATEFUL_MESSAGE_CONTEXT);
+        const source = decoded.sourceActor;
+        return {
+          kind: decoded.command,
+          ...(decoded.command === 'actorRequest' ? { correlation: decoded.correlation } : {}),
+          operation: decoded.operation,
+          messageFollowHopCount: decoded.messageFollowHopCount,
+          ...(source.actorId === null
+            ? {}
+            : {
+                sourceActor: {
+                  nodeRid: '',
+                  actorId: source.actorId,
+                  generation: source.generation!
+                }
+              }),
+          target: {
+            actor: {
+              nodeRid: fromGeneratedRoutingId(decoded.targetActor.targetNodeRid, 'targetNodeRid'),
+              actorId: decoded.targetActor.actor.actorId,
+              generation: decoded.targetActor.actor.objectGeneration
+            },
+            targetNodeGeneration: decoded.targetActor.targetNodeGeneration,
+            authorityOwnerGeneration: decoded.targetActor.expectedAuthorityOwnerGeneration,
+            ownerLeaseGeneration: decoded.targetActor.expectedOwnerLeaseGeneration
+          },
+          ...(decoded.boundSessionTail === undefined
+            ? {}
+            : {
+                boundSession: {
+                  sessionRid: fromGeneratedRoutingId(
+                    decoded.boundSessionTail.sourceSessionRid,
+                    'sourceSessionRid'
+                  ),
+                  bindingGeneration: decoded.boundSessionTail.sourceBindingGeneration,
+                  sequence: decoded.boundSessionTail.sourceSessionSequence
+                }
+              })
+        };
+      } catch (error) {
+        throw new ServiceWireProtocolError(
+          error instanceof Error ? error.message : 'Invalid stateful message.'
+        );
+      }
     }
+  }
+  const reader = new Reader(frame);
+  const command = reader.prefix();
+  switch (command.command) {
     case M6bServiceWireCommand.logicalMulticast: {
       requireFlags(command.flags, 0);
       const result = {
@@ -2124,20 +2258,6 @@ function actorAuthorityFence(value: ServiceBoundSessionActorAuthority): Buffer {
   );
 }
 
-function spotFence(value: ServiceSpotRouteFence): Buffer {
-  return concat(
-    spotRef(value.spot),
-    rid(value.targetNodeRid, 'targetNodeRid'),
-    u64(value.targetNodeGeneration),
-    u64(value.authorityOwnerGeneration),
-    u64(value.ownerLeaseGeneration)
-  );
-}
-
-function directSpotFence(value: ServiceDirectSpotRouteFence): Buffer {
-  return concat(spotFence(value), text16(value.storeVersion, 'storeVersion'));
-}
-
 function messageFollowRoute(value: ServiceMessageFollowRoute): Buffer {
   const body =
     value.kind === 'actor'
@@ -2205,12 +2325,6 @@ function actorRef(value: ServiceActorRef): Buffer {
   return concat(text8(value.actorId, 'actorId'), u64(value.generation));
 }
 
-function optionalActor(value: ServiceActorRef | undefined): Buffer {
-  return value === undefined
-    ? Buffer.of(0)
-    : concat(text8(value.actorId, 'sourceActorId'), u64(value.generation));
-}
-
 function spotRef(value: ServiceSpotRef): Buffer {
   return concat(rid(value.spotId, 'spotId'), u64(value.generation));
 }
@@ -2409,20 +2523,6 @@ class Reader {
     };
   }
 
-  optionalActor(): ServiceActorRef | undefined {
-    const length = this.u8('sourceActorId.length');
-    if (length === 0) return undefined;
-    this.need(length, 'sourceActorId');
-    const bytes = this.bytes.subarray(this.offset, this.offset + length);
-    this.offset += length;
-    const actorId = decodeCanonicalServiceWireText(bytes, 'sourceActorId', fail);
-    return {
-      nodeRid: '',
-      actorId,
-      generation: this.nonZeroU64('sourceActorGeneration')
-    };
-  }
-
   spotRef(): ServiceSpotRef {
     return {
       spotId: this.rid('spotId'),
@@ -2441,24 +2541,6 @@ class Reader {
     };
   }
 
-  spotFence(): ServiceSpotRouteFence {
-    const spot = this.spotRef();
-    return {
-      spot,
-      targetNodeRid: this.rid('targetNodeRid'),
-      targetNodeGeneration: this.nonZeroU64('targetNodeGeneration'),
-      authorityOwnerGeneration: this.nonZeroU64('authorityOwnerGeneration'),
-      ownerLeaseGeneration: this.nonZeroU64('ownerLeaseGeneration')
-    };
-  }
-
-  directSpotFence(): ServiceDirectSpotRouteFence {
-    return {
-      ...this.spotFence(),
-      storeVersion: this.text16('storeVersion')
-    };
-  }
-
   messageFollowRoute(name: string): ServiceMessageFollowRoute {
     const kind = this.u8(`${name}.objectKind`);
     const length = this.u16(`${name}.length`);

package/src/runtime/foundation/service-topology-registry.ts

@@ -34,8 +34,9 @@ export interface ServiceNodeDescriptor {
 
 export interface AdmittedServicePeer {
   readonly descriptor: ServiceNodeDescriptor;
+  // The Core selected-route generation this admission belongs to (Core ROUTER
+  // §10.1), as an opaque token compared only for equality.
   readonly connectionId: string;
-  readonly connectionDiscriminator: string;
 }
 
 export interface ServicePeerAdmissionExpectation {
@@ -98,13 +99,11 @@ export class ServiceTopologyRegistry {
   admit(
     descriptor: ServiceNodeDescriptor,
     connectionId: string,
-    expected?: ServicePeerAdmissionExpectation,
-    connectionDiscriminator = connectionId
+    expected?: ServicePeerAdmissionExpectation
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
       requireText(connectionId, 'connectionId');
-      requireText(connectionDiscriminator, 'connectionDiscriminator');
     } catch (error) {
       return 'invalidDescriptor';
     }
@@ -146,34 +145,11 @@ export class ServiceTopologyRegistry {
     ) {
       return 'staleDescriptor';
     }
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      current.descriptor.descriptorRevision === descriptor.descriptorRevision &&
-      sameServiceNodeDescriptor(current.descriptor, descriptor) &&
-      current.connectionId !== connectionId &&
-      // A fallback candidate is only a logical placeholder. Once the
-      // monitor reports the physical connection, its evidence supersedes
-      // candidate ordering so the request path uses the native route.
-      !(
-        isUnmonitoredConnectionId(current.connectionId) && !isUnmonitoredConnectionId(connectionId)
-      ) &&
-      compareConnectionCandidate(
-        current.connectionDiscriminator,
-        current.connectionId,
-        connectionDiscriminator,
-        connectionId
-      ) <= 0
-    ) {
-      // Both manual directions can reach admission. The same comparison on
-      // every retry keeps one physical candidate instead of replacing it in
-      // arrival order.
-      return 'staleDescriptor';
-    }
+    // Core selects the one route per RID (Core ROUTER §10.1); an admission on
+    // that route replaces the admission of a route it replaced.
     this.peersByRid.set(descriptor.nodeRoutingId, {
       descriptor: cloneDescriptor(descriptor),
-      connectionId,
-      connectionDiscriminator
+      connectionId
     });
     this.remember(descriptor);
     this.rebuildSelections();
@@ -286,8 +262,7 @@ export class ServiceTopologyRegistry {
       () => {
         const local: AdmittedServicePeer = {
           descriptor: cloneDescriptor(this.local),
-          connectionId: 'local',
-          connectionDiscriminator: 'local'
+          connectionId: 'local'
         };
         return [local, ...this.peersByRid.values()]
           .map((peer) => ({
@@ -549,8 +524,7 @@ function cloneDescriptor(descriptor: ServiceNodeDescriptor): ServiceNodeDescript
 function clonePeer(peer: AdmittedServicePeer): AdmittedServicePeer {
   return {
     descriptor: cloneDescriptor(peer.descriptor),
-    connectionId: peer.connectionId,
-    connectionDiscriminator: peer.connectionDiscriminator
+    connectionId: peer.connectionId
   };
 }
 
@@ -582,20 +556,6 @@ function arraysEqual(left: readonly string[], right: readonly string[]): boolean
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
-function isUnmonitoredConnectionId(connectionId: string): boolean {
-  return connectionId.startsWith('unmonitored:');
-}
-
-function compareConnectionCandidate(
-  leftDiscriminator: string,
-  leftId: string,
-  rightDiscriminator: string,
-  rightId: string
-): number {
-  const discriminator = compareOrdinal(leftDiscriminator, rightDiscriminator);
-  return discriminator === 0 ? compareOrdinal(leftId, rightId) : discriminator;
-}
-
 function compareOrdinal(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }