@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/host/instance-activation-authority.ts

@@ -41,6 +41,7 @@ import { putNewRelocationBlob, relocationBlobReference } from '../locations/relo
 
 import {
   encodeInstanceActivationRecoveryEnvelope,
+  decodeInstanceActivationRecoveryEnvelope,
   type ServiceInstanceActivationRecoveryEnvelope
 } from '../foundation/service-instance-activation-recovery-codec';
 
@@ -57,6 +58,9 @@ interface PendingReservation {
 }
 
 export interface ZLinkInstanceActivationAuthorityOptions {
+  readonly relocationPolicy?: (
+    stableType: string
+  ) => import('../locations/internal-location-contracts').ZLinkObjectReserveRequest['actorRelocationPolicy'];
   readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
   readonly relocationStore?: ZLinkRelocationStore;
   readonly meshName: string;
@@ -73,9 +77,101 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
 
   constructor(private readonly options: ZLinkInstanceActivationAuthorityOptions) {}
 
-  async read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead> {
-    const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
-    return current.kind === 'snapshot' ? readyRead(current, target) : { kind: 'missing' };
+  async read(
+    target: ServiceInstanceActivationTarget,
+    instanceIntent?: true,
+    activation?: ServiceInstanceActivationRecoveryEnvelope,
+    acceptsLocal?: (route: ServiceInstanceRouteFence) => boolean
+  ): Promise<ServiceInstanceAuthorityRead> {
+    const key = authorityKey(target.targetSpotId);
+    const current = await this.options.store.readAuthority(key);
+    if (current.kind !== 'snapshot') return { kind: 'missing' };
+    const ready = decodeServiceInstanceAuthorityPayload(current.payload);
+    const resolved = readyRead(current, target, ready);
+    if (
+      ready?.state === 'ready' &&
+      resolved.kind === 'ready' &&
+      acceptsLocal?.(resolved.route) === true
+    ) {
+      return resolved;
+    }
+    if (
+      activation !== undefined &&
+      current.allocation.objectKind === 'instance_spot' &&
+      routingIdsEqual(current.allocation.descriptor.rid, target.targetNodeRid) &&
+      current.allocation.descriptorLifecycleGeneration === target.targetNodeGeneration
+    ) {
+      const reference =
+        current.pendingCreation?.requestContentReference ?? ready?.activationRecovery?.reference;
+      if (reference !== undefined) {
+        const root = await this.options.relocationStore?.read(relocationBlobReference(reference));
+        if (root?.kind !== 'found') {
+          throw new ZLinkFrameworkException(
+            ZLinkFrameworkErrorKind.DataLost,
+            'Stored Instance activation is missing.'
+          );
+        }
+        let stored: ServiceInstanceActivationRecoveryEnvelope;
+        try {
+          stored = decodeInstanceActivationRecoveryEnvelope(root.bytes);
+        } catch (error) {
+          if (!(error instanceof TypeError || error instanceof RangeError)) throw error;
+          throw new ZLinkFrameworkException(
+            ZLinkFrameworkErrorKind.ProtocolError,
+            'Stored Instance activation is invalid.'
+          );
+        }
+        if (
+          stored.operation.high === activation.operation.high &&
+          stored.operation.low === activation.operation.low &&
+          (stored.targetMeshName !== activation.targetMeshName ||
+            stored.target.stableType !== target.stableType ||
+            stored.target.descriptorVersion !== target.descriptorVersion ||
+            stored.deadlineUnixMs !== activation.deadlineUnixMs ||
+            (stored.metadataFrame === undefined) !== (activation.metadataFrame === undefined) ||
+            (stored.metadataFrame !== undefined &&
+              activation.metadataFrame !== undefined &&
+              Buffer.compare(stored.metadataFrame, activation.metadataFrame) !== 0))
+        ) {
+          throw new ZLinkFrameworkException(
+            ZLinkFrameworkErrorKind.ProtocolError,
+            'Instance route does not match the stored activation.'
+          );
+        }
+      }
+    }
+
+    if (
+      instanceIntent === true &&
+      current.allocation.state === 'active' &&
+      ready?.state === 'ready'
+    ) {
+      if (
+        current.allocation.objectKind !== 'instance_spot' ||
+        current.allocation.stableType !== target.stableType
+      ) {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotTypeMismatch,
+          'Instance activation type does not match the current authority.'
+        );
+      }
+      const released = await this.options.store.releaseEndedReservation?.(
+        key,
+        current.storeVersion.value,
+        undefined,
+        {
+          key: { kind: 'instance_spot', globalId: target.targetSpotId },
+          intent: { stableType: target.stableType },
+          actorRelocationPolicy: this.options.relocationPolicy?.(target.stableType)
+        }
+      );
+      if (released === true) return { kind: 'missing' };
+      const refreshed = await this.options.store.readAuthority(key);
+      return refreshed.kind === 'snapshot'
+        ? readyRead(refreshed, target, decodeServiceInstanceAuthorityPayload(refreshed.payload))
+        : { kind: 'missing' };
+    }
+    return resolved;
   }
 
   async reserve(
@@ -117,6 +213,7 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
       reserved = await this.options.store.reserve(
         {
           key: { kind: 'instance_spot', globalId: target.targetSpotId },
+          actorRelocationPolicy: this.options.relocationPolicy?.(target.stableType),
           intent: {
             stableType: target.stableType,
             requestContentReference: stored.reference.value,
@@ -310,7 +407,11 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
     }
     const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
     if (current.kind === 'snapshot') {
-      const ready = readyRead(current, target);
+      const ready = readyRead(
+        current,
+        target,
+        decodeServiceInstanceAuthorityPayload(current.payload)
+      );
       if (ready.kind === 'ready') {
         this.pending.delete(reservation.token);
         return { kind: 'lost', route: ready.route };
@@ -344,7 +445,7 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
       throw new Error('Instance activation authority changed before inbox release.');
     }
     const recovery = decoded.activationRecovery;
-    if (recovery === undefined) return routeFromSnapshot(current);
+    if (recovery === undefined) return routeFromSnapshot(current, decoded.spotId);
     let completed = current;
     if (recovery.replayCursor < recovery.inboxSequence) {
       const cursorStored = await this.options.store.compareExchangeAuthority(
@@ -459,22 +560,19 @@ export class ZLinkInstanceActivationAuthority implements ServiceAsyncInstanceAct
 
 function readyRead(
   snapshot: ZLinkAuthoritySnapshot,
-  target: ServiceInstanceActivationTarget
+  target: ServiceInstanceActivationTarget,
+  decoded: ReturnType<typeof decodeServiceInstanceAuthorityPayload>
 ): ServiceInstanceAuthorityRead {
-  const decoded =
-    decodeServiceReadySpotAuthority(snapshot.payload) ??
-    decodeServiceClosingSpotAuthority(snapshot.payload);
-  const creating = decodeServiceInstanceAuthorityPayload(snapshot.payload);
   if (
-    creating?.state === 'coldActivating' &&
+    decoded?.state === 'coldActivating' &&
     snapshot.allocation.objectKind === 'instance_spot' &&
-    creating.stableType === target.stableType &&
-    creating.spotId === target.targetSpotId &&
-    creating.ownerId === snapshot.ownerId &&
-    creating.ownerLeaseGeneration === snapshot.ownerLeaseGeneration &&
-    creating.ownerMeshName === snapshot.allocation.descriptor.meshName &&
-    creating.ownerNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration &&
-    routingIdsEqual(creating.ownerNodeRid, snapshot.allocation.descriptor.rid) &&
+    decoded.stableType === target.stableType &&
+    decoded.spotId === target.targetSpotId &&
+    decoded.ownerId === snapshot.ownerId &&
+    decoded.ownerLeaseGeneration === snapshot.ownerLeaseGeneration &&
+    decoded.ownerMeshName === snapshot.allocation.descriptor.meshName &&
+    decoded.ownerNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration &&
+    routingIdsEqual(decoded.ownerNodeRid, snapshot.allocation.descriptor.rid) &&
     routingIdsEqual(target.targetNodeRid, snapshot.allocation.descriptor.rid) &&
     target.targetNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration
   ) {
@@ -486,7 +584,8 @@ function readyRead(
     };
   }
   if (
-    decoded?.kind !== 'instance_spot' ||
+    decoded === undefined ||
+    decoded.state === 'coldActivating' ||
     decoded.stableType !== target.stableType ||
     decoded.spotId !== target.targetSpotId ||
     snapshot.allocation.objectKind !== 'instance_spot' ||
@@ -501,7 +600,7 @@ function readyRead(
   ) {
     return { kind: 'missing' };
   }
-  return { kind: 'ready', route: routeFromSnapshot(snapshot), authority: snapshot };
+  return { kind: 'ready', route: routeFromSnapshot(snapshot, decoded.spotId), authority: snapshot };
 }
 
 function requireCommitIdentity(
@@ -529,17 +628,23 @@ function requireCommitIdentity(
   }
 }
 
-function routeFromSnapshot(snapshot: ZLinkAuthoritySnapshot): ServiceInstanceRouteFence {
-  const decoded =
-    decodeServiceReadySpotAuthority(snapshot.payload) ??
-    decodeServiceClosingSpotAuthority(snapshot.payload);
-  if (decoded?.kind !== 'instance_spot') {
-    throw new Error('Instance authority is not Ready.');
+function routeFromSnapshot(
+  snapshot: ZLinkAuthoritySnapshot,
+  spotId?: string
+): ServiceInstanceRouteFence {
+  if (spotId === undefined) {
+    const decoded =
+      decodeServiceReadySpotAuthority(snapshot.payload) ??
+      decodeServiceClosingSpotAuthority(snapshot.payload);
+    if (decoded?.kind !== 'instance_spot') {
+      throw new Error('Instance authority is not Ready.');
+    }
+    spotId = decoded.spotId;
   }
   return {
     targetNodeRid: String(snapshot.allocation.descriptor.rid),
     targetNodeGeneration: snapshot.allocation.descriptorLifecycleGeneration,
-    targetSpotId: decoded.spotId,
+    targetSpotId: spotId,
     objectGeneration: snapshot.objectGeneration,
     ownerId: snapshot.ownerId,
     authorityOwnerGeneration: snapshot.authorityOwnerGeneration,

package/src/runtime/host/remote-bound-session-relay.ts

@@ -845,24 +845,16 @@ function validateSessionRelocationRouteAgainstSeal(
   route: ServiceSessionRelocationRoute,
   sealed: ServiceSessionRelocationSealed
 ): void {
-  const sameCoordinator =
-    route.coordinator.ownerId === sealed.coordinator.ownerId &&
-    route.coordinator.leaseGeneration === sealed.coordinator.leaseGeneration &&
-    route.coordinator.nodeRid === sealed.coordinator.nodeRid &&
-    route.coordinator.nodeGeneration === sealed.coordinator.nodeGeneration &&
-    route.coordinator.expectedAuthorityStoreVersion ===
-      sealed.coordinator.expectedAuthorityStoreVersion;
   const sameSession =
-    route.session.sessionOwnerNodeRid === sealed.session.sessionOwnerNodeRid &&
+    routingIdsEqual(route.session.sessionOwnerNodeRid, sealed.session.sessionOwnerNodeRid) &&
     route.session.sessionOwnerNodeGeneration === sealed.session.sessionOwnerNodeGeneration &&
     route.session.sessionOwnerId === sealed.session.sessionOwnerId &&
     route.session.sessionOwnerLeaseGeneration === sealed.session.sessionOwnerLeaseGeneration &&
-    route.session.sessionRid === sealed.session.sessionRid &&
+    routingIdsEqual(route.session.sessionRid, sealed.session.sessionRid) &&
     route.session.bindingGeneration === sealed.session.bindingGeneration;
   if (
     route.relocation.high !== sealed.relocation.high ||
     route.relocation.low !== sealed.relocation.low ||
-    !sameCoordinator ||
     !sameSession ||
     route.actor.actorId !== sealed.actor.actor.actorId ||
     route.actor.generation !== sealed.actor.actor.generation
@@ -871,17 +863,4 @@ function validateSessionRelocationRouteAgainstSeal(
       `Session relocation '${serviceWireBarrierKey(route)}' changed its command 42 fence.`
     );
   }
-  if (route.route.action === 'commit') {
-    if (route.route.previousAuthorityOwnerGeneration !== sealed.actor.authorityOwnerGeneration) {
-      throw new ServiceWireProtocolError(
-        `Session relocation '${serviceWireBarrierKey(route)}' changed its source authority fence.`
-      );
-    }
-    return;
-  }
-  if (route.route.currentAuthorityOwnerGeneration !== sealed.actor.authorityOwnerGeneration) {
-    throw new ServiceWireProtocolError(
-      `Session relocation '${serviceWireBarrierKey(route)}' abort changed its authority fence.`
-    );
-  }
 }

package/src/runtime/host/route-mesh-runtime.ts

@@ -588,7 +588,7 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
           this.options.forceStopResources(meshName).catch(() => undefined)
         )
       );
-      result = { kind: 'forceStopped', reason };
+      result = { kind: 'forceStopped', reason, error };
       for (const [meshName, state] of entries) {
         this.transition(meshName, state, ZLinkTopologyState.Failed);
       }

package/src/runtime/host/service-relocation-control.ts

@@ -1,5 +1,6 @@
 import {
   SERVICE_WIRE_MAJOR_OFFSET,
+  SERVICE_WIRE_COMMAND_OFFSET,
   SERVICE_WIRE_PREFIX_SIZE
 } from '../foundation/service-wire-binary-primitives';
 import {
@@ -27,14 +28,19 @@ export function decodeServiceRelocationControlRequest(
   const bytes = Buffer.isBuffer(payload)
     ? payload
     : Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
+  if (serviceRelocationControlCommand(bytes) === undefined) return undefined;
+  return decodeMaintenanceRelocationControl(bytes);
+}
+
+export function serviceRelocationControlCommand(payload: Uint8Array): number | undefined {
   if (
-    bytes.byteLength < SERVICE_WIRE_PREFIX_SIZE ||
-    bytes[0] !== SERVICE_WIRE_MAGIC[0] ||
-    bytes[1] !== SERVICE_WIRE_MAGIC[1] ||
-    bytes[SERVICE_WIRE_MAJOR_OFFSET] !== SERVICE_WIRE_MAJOR
+    payload.byteLength < SERVICE_WIRE_PREFIX_SIZE ||
+    payload[0] !== SERVICE_WIRE_MAGIC[0] ||
+    payload[1] !== SERVICE_WIRE_MAGIC[1] ||
+    payload[SERVICE_WIRE_MAJOR_OFFSET] !== SERVICE_WIRE_MAJOR
   )
     return undefined;
-  return decodeMaintenanceRelocationControl(bytes);
+  return payload[SERVICE_WIRE_COMMAND_OFFSET];
 }
 
 export function encodeServiceRelocationControlResponse(