@adcops/autocore-react 3.3.8 → 3.3.10

package/src/core/CoreStreamTypes.ts

@@ -1,512 +1,512 @@
-/*
- * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
- *
- * CoreStream Protocol Types for TypeScript
- *
- * This module defines the JSON-wrapped CoreStream protocol used for
- * WebSocket communication between web clients and autocore-server.
- *
- * The protocol supports four message types:
- * - SDO: Service Data Object - read/write individual values
- * - Cyclic: Subscription-based push updates
- * - System: Module lifecycle (announce, health, start/stop)
- * - RPC: Remote procedure calls for arbitrary functions
- *
- * Addressing supports two modes:
- * - FQDN: Human-readable names like "vfd.frequency"
- * - Index:SubIndex: CANopen-style addresses like {index: 0x2000, subindex: 1}
- */
-
-// ============================================================================
-// Core Types
-// ============================================================================
-
-/** Message type discriminator */
-export type MessageType = "sdo" | "cyclic" | "system" | "rpc";
-
-/**
- * Address can be either a symbol name (FQDN) or CANopen-style index:subindex.
- * Modules accept both formats and resolve internally.
- */
-export type SymbolAddress =
-  | { symbol: string }                           // FQDN: "vfd.frequency"
-  | { index: number; subindex: number };         // OD: {index: 0x2000, subindex: 1}
-
-/** Data types supported by the protocol */
-export type DataType =
-  | "bool"
-  | "i8" | "i16" | "i32" | "i64"
-  | "u8" | "u16" | "u32" | "u64"
-  | "f32" | "f64"
-  | "string"
-  | "bytes"    // Base64-encoded binary
-  | "json";    // Arbitrary JSON value
-
-/** Access mode for symbols */
-export type AccessMode = "ro" | "wo" | "rw";
-
-// ============================================================================
-// Base Message Structure
-// ============================================================================
-
-/** Base structure for all CoreStream messages */
-export interface CoreStreamMessage<T extends MessageType = MessageType> {
-  /** Message type discriminator */
-  type: T;
-  /** Command within the message type */
-  command: string;
-  /** Request ID for request/response matching (optional for push messages) */
-  request_id?: number;
-  /** Message payload (type-specific) */
-  payload: unknown;
-}
-
-// ============================================================================
-// SDO Messages (Service Data Object - Read/Write)
-// ============================================================================
-
-export type SdoCommand =
-  | "upload_request"      // Read request (client → server)
-  | "upload_response"     // Read response (server → client)
-  | "download_request"    // Write request (client → server)
-  | "download_response"   // Write response (server → client)
-  | "abort";              // Error/abort
-
-/** SDO Upload Request - Read a value */
-export interface SdoUploadRequest extends CoreStreamMessage<"sdo"> {
-  command: "upload_request";
-  request_id: number;
-  payload: SymbolAddress;
-}
-
-/** SDO Upload Response - Read result */
-export interface SdoUploadResponse extends CoreStreamMessage<"sdo"> {
-  command: "upload_response";
-  request_id: number;
-  payload: {
-    /** The address that was read (echoed back) */
-    address: SymbolAddress;
-    /** The value read */
-    value: unknown;
-    /** Data type of the value */
-    datatype: DataType;
-  };
-}
-
-/** SDO Download Request - Write a value */
-export interface SdoDownloadRequest extends CoreStreamMessage<"sdo"> {
-  command: "download_request";
-  request_id: number;
-  payload: SymbolAddress & {
-    /** The value to write */
-    value: unknown;
-    /** Optional: data type hint */
-    datatype?: DataType;
-  };
-}
-
-/** SDO Download Response - Write acknowledgment */
-export interface SdoDownloadResponse extends CoreStreamMessage<"sdo"> {
-  command: "download_response";
-  request_id: number;
-  payload: {
-    /** The address that was written (echoed back) */
-    address: SymbolAddress;
-    /** Whether the write succeeded */
-    success: boolean;
-  };
-}
-
-/** SDO Abort - Error response */
-export interface SdoAbort extends CoreStreamMessage<"sdo"> {
-  command: "abort";
-  request_id: number;
-  payload: {
-    /** The address that caused the error */
-    address: SymbolAddress;
-    /** CANopen-style abort code */
-    abort_code: number;
-    /** Human-readable error message */
-    message: string;
-  };
-}
-
-/** Standard SDO abort codes (CANopen-compatible) */
-export const SdoAbortCode = {
-  TOGGLE_BIT_NOT_ALTERED: 0x05030000,
-  SDO_PROTOCOL_TIMEOUT: 0x05040000,
-  INVALID_COMMAND: 0x05040001,
-  OUT_OF_MEMORY: 0x05040005,
-  UNSUPPORTED_ACCESS: 0x06010000,
-  WRITE_ONLY: 0x06010001,
-  READ_ONLY: 0x06010002,
-  OBJECT_NOT_EXIST: 0x06020000,
-  SUBINDEX_NOT_EXIST: 0x06090011,
-  GENERAL_ERROR: 0x08000000,
-  DATA_TRANSFER_ERROR: 0x08000020,
-  DATA_LENGTH_MISMATCH: 0x08000022,
-} as const;
-
-export type SdoMessage =
-  | SdoUploadRequest
-  | SdoUploadResponse
-  | SdoDownloadRequest
-  | SdoDownloadResponse
-  | SdoAbort;
-
-// ============================================================================
-// Cyclic Messages (Subscriptions and Push Updates)
-// ============================================================================
-
-export type CyclicCommand =
-  | "subscribe"           // Subscribe to updates
-  | "subscribe_ack"       // Subscribe acknowledgment
-  | "unsubscribe"         // Unsubscribe
-  | "unsubscribe_ack"     // Unsubscribe acknowledgment
-  | "data_update"         // Single value update (push)
-  | "data_update_batch";  // Multiple values update (push)
-
-/** Subscription options for cyclic updates */
-export interface SubscriptionOptions {
-  /** Minimum interval between updates in milliseconds */
-  sampling_interval_ms?: number;
-  /** Only send updates when value changes */
-  on_change_only?: boolean;
-  /** Deadband as percentage of full scale (0-100) */
-  deadband_percent?: number;
-  /** Deadband as absolute value */
-  deadband_absolute?: number;
-  /** Queue size for buffering (default: 1 = latest only) */
-  queue_size?: number;
-}
-
-/** Subscribe to cyclic updates for a symbol */
-export interface CyclicSubscribe extends CoreStreamMessage<"cyclic"> {
-  command: "subscribe";
-  request_id: number;
-  payload: SymbolAddress & {
-    /** Optional subscription options */
-    options?: SubscriptionOptions;
-  };
-}
-
-/** Subscribe acknowledgment */
-export interface CyclicSubscribeAck extends CoreStreamMessage<"cyclic"> {
-  command: "subscribe_ack";
-  request_id: number;
-  payload: {
-    /** The address subscribed to */
-    address: SymbolAddress;
-    /** Whether subscription succeeded */
-    success: boolean;
-    /** Error message if failed */
-    error?: string;
-    /** Effective options after server clamping */
-    effective_options?: SubscriptionOptions;
-  };
-}
-
-/** Unsubscribe from cyclic updates */
-export interface CyclicUnsubscribe extends CoreStreamMessage<"cyclic"> {
-  command: "unsubscribe";
-  request_id: number;
-  payload: SymbolAddress;
-}
-
-/** Unsubscribe acknowledgment */
-export interface CyclicUnsubscribeAck extends CoreStreamMessage<"cyclic"> {
-  command: "unsubscribe_ack";
-  request_id: number;
-  payload: {
-    address: SymbolAddress;
-    success: boolean;
-  };
-}
-
-/** Single value update (pushed from server) */
-export interface CyclicDataUpdate extends CoreStreamMessage<"cyclic"> {
-  command: "data_update";
-  payload: {
-    /** The symbol that changed */
-    symbol: string;
-    /** The new value */
-    value: unknown;
-    /** Server timestamp (nanoseconds since epoch, optional) */
-    timestamp_ns?: number;
-    /** Data type */
-    datatype?: DataType;
-  };
-}
-
-/** Batch value update (multiple values in one message) */
-export interface CyclicDataUpdateBatch extends CoreStreamMessage<"cyclic"> {
-  command: "data_update_batch";
-  payload: {
-    /** Array of updates */
-    updates: Array<{
-      symbol: string;
-      value: unknown;
-      timestamp_ns?: number;
-      datatype?: DataType;
-    }>;
-  };
-}
-
-export type CyclicMessage =
-  | CyclicSubscribe
-  | CyclicSubscribeAck
-  | CyclicUnsubscribe
-  | CyclicUnsubscribeAck
-  | CyclicDataUpdate
-  | CyclicDataUpdateBatch;
-
-// ============================================================================
-// System Messages (Module Lifecycle)
-// ============================================================================
-
-export type SystemCommand =
-  | "announce"            // Module registration
-  | "announce_ack"        // Registration acknowledgment
-  | "discovery"           // Request all modules
-  | "discovery_response"  // Module list
-  | "leaving"             // Module disconnecting
-  | "start"               // Start cyclic operation
-  | "stop"                // Stop cyclic operation
-  | "health_request"      // Health check
-  | "health_response";    // Health status
-
-/** Symbol descriptor in module announcement */
-export interface SymbolDescriptor {
-  /** Human-readable symbol name (FQDN within module) */
-  name: string;
-  /** CANopen-style index */
-  index: number;
-  /** CANopen-style subindex */
-  subindex: number;
-  /** Data type */
-  datatype: DataType;
-  /** Access mode */
-  access: AccessMode;
-  /** Optional description */
-  description?: string;
-  /** Optional unit (e.g., "mm", "Hz") */
-  unit?: string;
-  /** Optional min value (for validation) */
-  min?: number;
-  /** Optional max value (for validation) */
-  max?: number;
-}
-
-/** Module capabilities */
-export interface ModuleCapabilities {
-  /** Supports SDO read */
-  sdo_read: boolean;
-  /** Supports SDO write */
-  sdo_write: boolean;
-  /** Supports cyclic subscriptions */
-  cyclic: boolean;
-  /** Supports batch operations */
-  batch: boolean;
-  /** Maximum symbols per batch */
-  max_batch_size?: number;
-}
-
-/** Module announces itself and its symbol catalog */
-export interface SystemAnnounce extends CoreStreamMessage<"system"> {
-  command: "announce";
-  payload: {
-    /** Module name (used as FQDN prefix) */
-    module_name: string;
-    /** Module version */
-    version?: string;
-    /** Module capabilities */
-    capabilities: ModuleCapabilities;
-    /** Symbol catalog */
-    symbols: SymbolDescriptor[];
-  };
-}
-
-/** Announcement acknowledgment */
-export interface SystemAnnounceAck extends CoreStreamMessage<"system"> {
-  command: "announce_ack";
-  payload: {
-    /** Whether announcement was accepted */
-    success: boolean;
-    /** Assigned module ID (if applicable) */
-    module_id?: number;
-    /** Error message if failed */
-    error?: string;
-  };
-}
-
-/** Request list of all connected modules */
-export interface SystemDiscovery extends CoreStreamMessage<"system"> {
-  command: "discovery";
-  request_id: number;
-  payload: Record<string, never>;  // Empty object
-}
-
-/** Discovery response with module list */
-export interface SystemDiscoveryResponse extends CoreStreamMessage<"system"> {
-  command: "discovery_response";
-  request_id: number;
-  payload: {
-    modules: Array<{
-      module_name: string;
-      version?: string;
-      capabilities: ModuleCapabilities;
-      symbol_count: number;
-      state: "running" | "stopped" | "error";
-    }>;
-  };
-}
-
-/** Module leaving notification */
-export interface SystemLeaving extends CoreStreamMessage<"system"> {
-  command: "leaving";
-  payload: {
-    module_name: string;
-    reason?: string;
-  };
-}
-
-/** Health check request */
-export interface SystemHealthRequest extends CoreStreamMessage<"system"> {
-  command: "health_request";
-  request_id: number;
-  payload: {
-    /** Optional: specific module to check */
-    module_name?: string;
-  };
-}
-
-/** Health check response */
-export interface SystemHealthResponse extends CoreStreamMessage<"system"> {
-  command: "health_response";
-  request_id: number;
-  payload: {
-    healthy: boolean;
-    modules: Array<{
-      module_name: string;
-      state: "running" | "stopped" | "error";
-      uptime_secs?: number;
-      error?: string;
-    }>;
-  };
-}
-
-export type SystemMessage =
-  | SystemAnnounce
-  | SystemAnnounceAck
-  | SystemDiscovery
-  | SystemDiscoveryResponse
-  | SystemLeaving
-  | SystemHealthRequest
-  | SystemHealthResponse;
-
-// ============================================================================
-// RPC Messages (Remote Procedure Calls)
-// ============================================================================
-
-export type RpcCommand =
-  | "invoke"              // Call a function
-  | "response";           // Function result
-
-/** RPC invoke request - call a function on a module */
-export interface RpcInvoke extends CoreStreamMessage<"rpc"> {
-  command: "invoke";
-  request_id: number;
-  payload: {
-    /** Target module name */
-    module: string;
-    /** Method/function name */
-    method: string;
-    /** Arguments (JSON object) */
-    args?: Record<string, unknown>;
-  };
-}
-
-/** RPC response - function result */
-export interface RpcResponse extends CoreStreamMessage<"rpc"> {
-  command: "response";
-  request_id: number;
-  payload: {
-    /** Whether the call succeeded */
-    success: boolean;
-    /** Return value (if success) */
-    data?: unknown;
-    /** Error message (if failed) */
-    error?: string;
-    /** Error code (if failed) */
-    error_code?: number;
-  };
-}
-
-export type RpcMessage = RpcInvoke | RpcResponse;
-
-// ============================================================================
-// Union Type for All Messages
-// ============================================================================
-
-export type AnyCoreSteamMessage =
-  | SdoMessage
-  | CyclicMessage
-  | SystemMessage
-  | RpcMessage;
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-/** Type guard for SDO messages */
-export function isSdoMessage(msg: CoreStreamMessage): msg is SdoMessage {
-  return msg.type === "sdo";
-}
-
-/** Type guard for Cyclic messages */
-export function isCyclicMessage(msg: CoreStreamMessage): msg is CyclicMessage {
-  return msg.type === "cyclic";
-}
-
-/** Type guard for System messages */
-export function isSystemMessage(msg: CoreStreamMessage): msg is SystemMessage {
-  return msg.type === "system";
-}
-
-/** Type guard for RPC messages */
-export function isRpcMessage(msg: CoreStreamMessage): msg is RpcMessage {
-  return msg.type === "rpc";
-}
-
-/** Check if an address uses symbol format */
-export function isSymbolAddress(addr: SymbolAddress): addr is { symbol: string } {
-  return "symbol" in addr;
-}
-
-/** Check if an address uses index:subindex format */
-export function isIndexAddress(addr: SymbolAddress): addr is { index: number; subindex: number } {
-  return "index" in addr && "subindex" in addr;
-}
-
-/** Convert address to string for display/logging */
-export function addressToString(addr: SymbolAddress): string {
-  if (isSymbolAddress(addr)) {
-    return addr.symbol;
-  } else {
-    return `0x${addr.index.toString(16).padStart(4, '0')}:${addr.subindex.toString(16).padStart(2, '0')}`;
-  }
-}
-
-/** Parse an address string (either "vfd.frequency" or "0x2000:01") */
-export function parseAddress(str: string): SymbolAddress {
-  // Check for hex format: 0xNNNN:NN or NNNN:NN
-  const hexMatch = str.match(/^(?:0x)?([0-9a-fA-F]{1,4}):([0-9a-fA-F]{1,2})$/);
-  if (hexMatch) {
-    return {
-      index: parseInt(hexMatch[1], 16),
-      subindex: parseInt(hexMatch[2], 16),
-    };
-  }
-  // Otherwise treat as symbol name
-  return { symbol: str };
-}
+/*
+ * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
+ *
+ * CoreStream Protocol Types for TypeScript
+ *
+ * This module defines the JSON-wrapped CoreStream protocol used for
+ * WebSocket communication between web clients and autocore-server.
+ *
+ * The protocol supports four message types:
+ * - SDO: Service Data Object - read/write individual values
+ * - Cyclic: Subscription-based push updates
+ * - System: Module lifecycle (announce, health, start/stop)
+ * - RPC: Remote procedure calls for arbitrary functions
+ *
+ * Addressing supports two modes:
+ * - FQDN: Human-readable names like "vfd.frequency"
+ * - Index:SubIndex: CANopen-style addresses like {index: 0x2000, subindex: 1}
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/** Message type discriminator */
+export type MessageType = "sdo" | "cyclic" | "system" | "rpc";
+
+/**
+ * Address can be either a symbol name (FQDN) or CANopen-style index:subindex.
+ * Modules accept both formats and resolve internally.
+ */
+export type SymbolAddress =
+  | { symbol: string }                           // FQDN: "vfd.frequency"
+  | { index: number; subindex: number };         // OD: {index: 0x2000, subindex: 1}
+
+/** Data types supported by the protocol */
+export type DataType =
+  | "bool"
+  | "i8" | "i16" | "i32" | "i64"
+  | "u8" | "u16" | "u32" | "u64"
+  | "f32" | "f64"
+  | "string"
+  | "bytes"    // Base64-encoded binary
+  | "json";    // Arbitrary JSON value
+
+/** Access mode for symbols */
+export type AccessMode = "ro" | "wo" | "rw";
+
+// ============================================================================
+// Base Message Structure
+// ============================================================================
+
+/** Base structure for all CoreStream messages */
+export interface CoreStreamMessage<T extends MessageType = MessageType> {
+  /** Message type discriminator */
+  type: T;
+  /** Command within the message type */
+  command: string;
+  /** Request ID for request/response matching (optional for push messages) */
+  request_id?: number;
+  /** Message payload (type-specific) */
+  payload: unknown;
+}
+
+// ============================================================================
+// SDO Messages (Service Data Object - Read/Write)
+// ============================================================================
+
+export type SdoCommand =
+  | "upload_request"      // Read request (client → server)
+  | "upload_response"     // Read response (server → client)
+  | "download_request"    // Write request (client → server)
+  | "download_response"   // Write response (server → client)
+  | "abort";              // Error/abort
+
+/** SDO Upload Request - Read a value */
+export interface SdoUploadRequest extends CoreStreamMessage<"sdo"> {
+  command: "upload_request";
+  request_id: number;
+  payload: SymbolAddress;
+}
+
+/** SDO Upload Response - Read result */
+export interface SdoUploadResponse extends CoreStreamMessage<"sdo"> {
+  command: "upload_response";
+  request_id: number;
+  payload: {
+    /** The address that was read (echoed back) */
+    address: SymbolAddress;
+    /** The value read */
+    value: unknown;
+    /** Data type of the value */
+    datatype: DataType;
+  };
+}
+
+/** SDO Download Request - Write a value */
+export interface SdoDownloadRequest extends CoreStreamMessage<"sdo"> {
+  command: "download_request";
+  request_id: number;
+  payload: SymbolAddress & {
+    /** The value to write */
+    value: unknown;
+    /** Optional: data type hint */
+    datatype?: DataType;
+  };
+}
+
+/** SDO Download Response - Write acknowledgment */
+export interface SdoDownloadResponse extends CoreStreamMessage<"sdo"> {
+  command: "download_response";
+  request_id: number;
+  payload: {
+    /** The address that was written (echoed back) */
+    address: SymbolAddress;
+    /** Whether the write succeeded */
+    success: boolean;
+  };
+}
+
+/** SDO Abort - Error response */
+export interface SdoAbort extends CoreStreamMessage<"sdo"> {
+  command: "abort";
+  request_id: number;
+  payload: {
+    /** The address that caused the error */
+    address: SymbolAddress;
+    /** CANopen-style abort code */
+    abort_code: number;
+    /** Human-readable error message */
+    message: string;
+  };
+}
+
+/** Standard SDO abort codes (CANopen-compatible) */
+export const SdoAbortCode = {
+  TOGGLE_BIT_NOT_ALTERED: 0x05030000,
+  SDO_PROTOCOL_TIMEOUT: 0x05040000,
+  INVALID_COMMAND: 0x05040001,
+  OUT_OF_MEMORY: 0x05040005,
+  UNSUPPORTED_ACCESS: 0x06010000,
+  WRITE_ONLY: 0x06010001,
+  READ_ONLY: 0x06010002,
+  OBJECT_NOT_EXIST: 0x06020000,
+  SUBINDEX_NOT_EXIST: 0x06090011,
+  GENERAL_ERROR: 0x08000000,
+  DATA_TRANSFER_ERROR: 0x08000020,
+  DATA_LENGTH_MISMATCH: 0x08000022,
+} as const;
+
+export type SdoMessage =
+  | SdoUploadRequest
+  | SdoUploadResponse
+  | SdoDownloadRequest
+  | SdoDownloadResponse
+  | SdoAbort;
+
+// ============================================================================
+// Cyclic Messages (Subscriptions and Push Updates)
+// ============================================================================
+
+export type CyclicCommand =
+  | "subscribe"           // Subscribe to updates
+  | "subscribe_ack"       // Subscribe acknowledgment
+  | "unsubscribe"         // Unsubscribe
+  | "unsubscribe_ack"     // Unsubscribe acknowledgment
+  | "data_update"         // Single value update (push)
+  | "data_update_batch";  // Multiple values update (push)
+
+/** Subscription options for cyclic updates */
+export interface SubscriptionOptions {
+  /** Minimum interval between updates in milliseconds */
+  sampling_interval_ms?: number;
+  /** Only send updates when value changes */
+  on_change_only?: boolean;
+  /** Deadband as percentage of full scale (0-100) */
+  deadband_percent?: number;
+  /** Deadband as absolute value */
+  deadband_absolute?: number;
+  /** Queue size for buffering (default: 1 = latest only) */
+  queue_size?: number;
+}
+
+/** Subscribe to cyclic updates for a symbol */
+export interface CyclicSubscribe extends CoreStreamMessage<"cyclic"> {
+  command: "subscribe";
+  request_id: number;
+  payload: SymbolAddress & {
+    /** Optional subscription options */
+    options?: SubscriptionOptions;
+  };
+}
+
+/** Subscribe acknowledgment */
+export interface CyclicSubscribeAck extends CoreStreamMessage<"cyclic"> {
+  command: "subscribe_ack";
+  request_id: number;
+  payload: {
+    /** The address subscribed to */
+    address: SymbolAddress;
+    /** Whether subscription succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Effective options after server clamping */
+    effective_options?: SubscriptionOptions;
+  };
+}
+
+/** Unsubscribe from cyclic updates */
+export interface CyclicUnsubscribe extends CoreStreamMessage<"cyclic"> {
+  command: "unsubscribe";
+  request_id: number;
+  payload: SymbolAddress;
+}
+
+/** Unsubscribe acknowledgment */
+export interface CyclicUnsubscribeAck extends CoreStreamMessage<"cyclic"> {
+  command: "unsubscribe_ack";
+  request_id: number;
+  payload: {
+    address: SymbolAddress;
+    success: boolean;
+  };
+}
+
+/** Single value update (pushed from server) */
+export interface CyclicDataUpdate extends CoreStreamMessage<"cyclic"> {
+  command: "data_update";
+  payload: {
+    /** The symbol that changed */
+    symbol: string;
+    /** The new value */
+    value: unknown;
+    /** Server timestamp (nanoseconds since epoch, optional) */
+    timestamp_ns?: number;
+    /** Data type */
+    datatype?: DataType;
+  };
+}
+
+/** Batch value update (multiple values in one message) */
+export interface CyclicDataUpdateBatch extends CoreStreamMessage<"cyclic"> {
+  command: "data_update_batch";
+  payload: {
+    /** Array of updates */
+    updates: Array<{
+      symbol: string;
+      value: unknown;
+      timestamp_ns?: number;
+      datatype?: DataType;
+    }>;
+  };
+}
+
+export type CyclicMessage =
+  | CyclicSubscribe
+  | CyclicSubscribeAck
+  | CyclicUnsubscribe
+  | CyclicUnsubscribeAck
+  | CyclicDataUpdate
+  | CyclicDataUpdateBatch;
+
+// ============================================================================
+// System Messages (Module Lifecycle)
+// ============================================================================
+
+export type SystemCommand =
+  | "announce"            // Module registration
+  | "announce_ack"        // Registration acknowledgment
+  | "discovery"           // Request all modules
+  | "discovery_response"  // Module list
+  | "leaving"             // Module disconnecting
+  | "start"               // Start cyclic operation
+  | "stop"                // Stop cyclic operation
+  | "health_request"      // Health check
+  | "health_response";    // Health status
+
+/** Symbol descriptor in module announcement */
+export interface SymbolDescriptor {
+  /** Human-readable symbol name (FQDN within module) */
+  name: string;
+  /** CANopen-style index */
+  index: number;
+  /** CANopen-style subindex */
+  subindex: number;
+  /** Data type */
+  datatype: DataType;
+  /** Access mode */
+  access: AccessMode;
+  /** Optional description */
+  description?: string;
+  /** Optional unit (e.g., "mm", "Hz") */
+  unit?: string;
+  /** Optional min value (for validation) */
+  min?: number;
+  /** Optional max value (for validation) */
+  max?: number;
+}
+
+/** Module capabilities */
+export interface ModuleCapabilities {
+  /** Supports SDO read */
+  sdo_read: boolean;
+  /** Supports SDO write */
+  sdo_write: boolean;
+  /** Supports cyclic subscriptions */
+  cyclic: boolean;
+  /** Supports batch operations */
+  batch: boolean;
+  /** Maximum symbols per batch */
+  max_batch_size?: number;
+}
+
+/** Module announces itself and its symbol catalog */
+export interface SystemAnnounce extends CoreStreamMessage<"system"> {
+  command: "announce";
+  payload: {
+    /** Module name (used as FQDN prefix) */
+    module_name: string;
+    /** Module version */
+    version?: string;
+    /** Module capabilities */
+    capabilities: ModuleCapabilities;
+    /** Symbol catalog */
+    symbols: SymbolDescriptor[];
+  };
+}
+
+/** Announcement acknowledgment */
+export interface SystemAnnounceAck extends CoreStreamMessage<"system"> {
+  command: "announce_ack";
+  payload: {
+    /** Whether announcement was accepted */
+    success: boolean;
+    /** Assigned module ID (if applicable) */
+    module_id?: number;
+    /** Error message if failed */
+    error?: string;
+  };
+}
+
+/** Request list of all connected modules */
+export interface SystemDiscovery extends CoreStreamMessage<"system"> {
+  command: "discovery";
+  request_id: number;
+  payload: Record<string, never>;  // Empty object
+}
+
+/** Discovery response with module list */
+export interface SystemDiscoveryResponse extends CoreStreamMessage<"system"> {
+  command: "discovery_response";
+  request_id: number;
+  payload: {
+    modules: Array<{
+      module_name: string;
+      version?: string;
+      capabilities: ModuleCapabilities;
+      symbol_count: number;
+      state: "running" | "stopped" | "error";
+    }>;
+  };
+}
+
+/** Module leaving notification */
+export interface SystemLeaving extends CoreStreamMessage<"system"> {
+  command: "leaving";
+  payload: {
+    module_name: string;
+    reason?: string;
+  };
+}
+
+/** Health check request */
+export interface SystemHealthRequest extends CoreStreamMessage<"system"> {
+  command: "health_request";
+  request_id: number;
+  payload: {
+    /** Optional: specific module to check */
+    module_name?: string;
+  };
+}
+
+/** Health check response */
+export interface SystemHealthResponse extends CoreStreamMessage<"system"> {
+  command: "health_response";
+  request_id: number;
+  payload: {
+    healthy: boolean;
+    modules: Array<{
+      module_name: string;
+      state: "running" | "stopped" | "error";
+      uptime_secs?: number;
+      error?: string;
+    }>;
+  };
+}
+
+export type SystemMessage =
+  | SystemAnnounce
+  | SystemAnnounceAck
+  | SystemDiscovery
+  | SystemDiscoveryResponse
+  | SystemLeaving
+  | SystemHealthRequest
+  | SystemHealthResponse;
+
+// ============================================================================
+// RPC Messages (Remote Procedure Calls)
+// ============================================================================
+
+export type RpcCommand =
+  | "invoke"              // Call a function
+  | "response";           // Function result
+
+/** RPC invoke request - call a function on a module */
+export interface RpcInvoke extends CoreStreamMessage<"rpc"> {
+  command: "invoke";
+  request_id: number;
+  payload: {
+    /** Target module name */
+    module: string;
+    /** Method/function name */
+    method: string;
+    /** Arguments (JSON object) */
+    args?: Record<string, unknown>;
+  };
+}
+
+/** RPC response - function result */
+export interface RpcResponse extends CoreStreamMessage<"rpc"> {
+  command: "response";
+  request_id: number;
+  payload: {
+    /** Whether the call succeeded */
+    success: boolean;
+    /** Return value (if success) */
+    data?: unknown;
+    /** Error message (if failed) */
+    error?: string;
+    /** Error code (if failed) */
+    error_code?: number;
+  };
+}
+
+export type RpcMessage = RpcInvoke | RpcResponse;
+
+// ============================================================================
+// Union Type for All Messages
+// ============================================================================
+
+export type AnyCoreSteamMessage =
+  | SdoMessage
+  | CyclicMessage
+  | SystemMessage
+  | RpcMessage;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/** Type guard for SDO messages */
+export function isSdoMessage(msg: CoreStreamMessage): msg is SdoMessage {
+  return msg.type === "sdo";
+}
+
+/** Type guard for Cyclic messages */
+export function isCyclicMessage(msg: CoreStreamMessage): msg is CyclicMessage {
+  return msg.type === "cyclic";
+}
+
+/** Type guard for System messages */
+export function isSystemMessage(msg: CoreStreamMessage): msg is SystemMessage {
+  return msg.type === "system";
+}
+
+/** Type guard for RPC messages */
+export function isRpcMessage(msg: CoreStreamMessage): msg is RpcMessage {
+  return msg.type === "rpc";
+}
+
+/** Check if an address uses symbol format */
+export function isSymbolAddress(addr: SymbolAddress): addr is { symbol: string } {
+  return "symbol" in addr;
+}
+
+/** Check if an address uses index:subindex format */
+export function isIndexAddress(addr: SymbolAddress): addr is { index: number; subindex: number } {
+  return "index" in addr && "subindex" in addr;
+}
+
+/** Convert address to string for display/logging */
+export function addressToString(addr: SymbolAddress): string {
+  if (isSymbolAddress(addr)) {
+    return addr.symbol;
+  } else {
+    return `0x${addr.index.toString(16).padStart(4, '0')}:${addr.subindex.toString(16).padStart(2, '0')}`;
+  }
+}
+
+/** Parse an address string (either "vfd.frequency" or "0x2000:01") */
+export function parseAddress(str: string): SymbolAddress {
+  // Check for hex format: 0xNNNN:NN or NNNN:NN
+  const hexMatch = str.match(/^(?:0x)?([0-9a-fA-F]{1,4}):([0-9a-fA-F]{1,2})$/);
+  if (hexMatch) {
+    return {
+      index: parseInt(hexMatch[1], 16),
+      subindex: parseInt(hexMatch[2], 16),
+    };
+  }
+  // Otherwise treat as symbol name
+  return { symbol: str };
+}