feat(connect): consume ClusterActivation.dtype in transport and SDK bindings (#1053)

SH
5d ago
+1231-3

Description

Resolves #1053 by consuming ClusterActivation.dtype in the Connect transport layer, decoding tensor_data with big-endian byte-swapping, validating expected tensor formats with typed errors, and binding the four exported rac_connect_cluster_* symbols into Swift SDK CppBridge.Connect and Android JNI.

Summary of Changes

1. Transport Activation Decoding & Format Validation

  • rac_connect_cluster_decode_activation_proto:
    • Reads ClusterActivation.dtype first. Rejects unspecified or unknown dtype values with RAC_ERROR_INVALID_FORMAT.
    • Supports format matching against expected_dtype requested by a receiver: returns typed error RAC_ERROR_INVALID_FORMAT if the sender's declared dtype does not match the receiver's expected format.
    • Validates exact byte count (tensor_data().size() == seq_len * hidden_size * element_size), rejecting mismatched payloads with RAC_ERROR_INVALID_FORMAT.
    • Guards against multiplication overflow when calculating expected byte count.
    • Decodes little-endian wire elements into host byte order (swapping 16-bit and 32-bit words on big-endian architectures).
    • Populates decoded tensor dimensions and metadata (rac_connect_decoded_activation_t).
  • rac_connect_transport_receive_activation:
    • Receives ClusterActivation payload from a transport channel and decodes tensor_data using the declared dtype with typed format validation.

2. SDK Bindings

  • Swift (CppBridge+Connect.swift):
    • Exposed the four exported rac_connect_cluster_* entry points:
      • CppBridge.Connect.startCluster(_:) -> RAClusterState
      • CppBridge.Connect.joinCluster(_:) -> RAClusterStartResponse
      • CppBridge.Connect.stopCluster(_:) -> RAClusterState
      • CppBridge.Connect.validateActivation(_:) -> RAConnectInvocationValidation
  • Android JNI (runanywhere_commons_jni.cpp):
    • Added JNI bridge functions for racConnectClusterStartProto, racConnectClusterJoinProto, racConnectClusterStopProto, and racConnectClusterValidateActivationProto.

3. IDL & Schema Updates

  • idl/connect.proto & core/include/rac/connect/rac_connect.h:
    • Documented the 2D flattening order for ClusterActivation.tensor_data as row-major (seq_len x hidden_size) little-endian.
    • Bumped idl/VERSION patch to 1.6.1 and updated idl/SCHEMA_LOCK.

4. Tests

  • core/tests/test_connect_proto_abi.cpp:
    • Added test_cluster_activation_decoding_and_transport() covering:
      • FP16, BF16, and FP32 activation decoding and metadata verification.
      • Format mismatch rejection with RAC_ERROR_INVALID_FORMAT (receiver expecting FP32, sender declared FP16).
      • Payload size mismatch rejection with RAC_ERROR_INVALID_FORMAT (FP32 declared with FP16-sized bytes).
      • Unspecified and out-of-range dtype rejection.
      • Zero dimension and dimension overflow rejection with RAC_ERROR_INVALID_ARGUMENT.
      • Integration test with rac_connect_transport_receive_activation using a mock channel.
    • Pinned rejection reasons in test_cluster_orchestration() for overflow and out-of-range dtype.

Closes #1053.

Summary by cubic

Adds a cluster orchestration runtime (start, join, stop, validate activation) and consumes ClusterActivation.dtype during transport decoding, validating tensor format and byte counts with typed errors.

Cluster runtime

  • New ClusterRuntime handles coordinator state, layer assignment validation, idempotent starts, and peer joins with typed accept/reject reasons.
  • New proto messages for cluster start, join, stop, and activation validation; IDL bumped to 1.6.1.

Activation decode and SDK bindings

  • rac_connect_cluster_decode_activation_proto and rac_connect_transport_receive_activation reject unspecified or mismatched dtypes, exact payload-size mismatches, and dimension overflows with RAC_ERROR_INVALID_FORMAT / RAC_ERROR_INVALID_ARGUMENT.
  • Wire elements are little-endian and swapped to host byte order on big-endian architectures.
  • Swift CppBridge.Connect and Android JNI expose start, join, stop, and validate activation entry points.

Summary by CodeRabbit

  • New Features
    • Added support for starting, joining, and stopping Connect clusters, with peer and layer assignment checks.
    • Added validation and decoding for intermediate cluster activations, including FP16, BF16, and FP32 tensor data.
    • Added transport support for receiving activation data and returning decoded tensor information.