@alteriom/mqtt-schema 0.4.0 → 0.6.0

package/README.md

@@ -33,6 +33,9 @@ Firmware emits structured MQTT payloads that must remain tightly aligned with we
 - Helpful error paths (JSON Pointer style)
 - Lightweight (Ajv peer dependency, schemas embedded)
 - Ships original schema JSON files (optional consumption)
+- **NEW in v0.6.0**: Enhanced location/geolocation support for asset tracking
+- **NEW in v0.6.0**: Extended sensor metadata (accuracy, calibration, operational range)
+- **NEW in v0.6.0**: Comprehensive gateway health metrics (storage, network, errors)
 
 ## Installation
 
@@ -89,6 +92,206 @@ Access raw schema JSON (if you need to introspect or power form generation):
 import envelopeSchema from '@alteriom/mqtt-schema/schemas/envelope.schema.json';
 ```
 
+## Command & Control (v0.5.0+)
+
+Send commands to devices and receive responses with correlation tracking:
+
+```ts
+import { validators, isCommandMessage, isCommandResponseMessage } from '@alteriom/mqtt-schema';
+
+// Create a command message
+const command = {
+  schema_version: 1,
+  device_id: 'ALT-441D64F804A0',
+  device_type: 'sensor',
+  timestamp: new Date().toISOString(),
+  firmware_version: 'WEB 1.0.0',
+  event: 'command',
+  command: 'read_sensors',
+  correlation_id: `cmd-${Date.now()}-001`,
+  parameters: {
+    immediate: true,
+    sensors: ['temperature', 'humidity']
+  },
+  priority: 'high'
+};
+
+// Validate before sending
+const cmdResult = validators.command(command);
+if (cmdResult.valid) {
+  // Publish to MQTT topic: alteriom/nodes/{device_id}/commands
+  mqttClient.publish(`alteriom/nodes/${command.device_id}/commands`, JSON.stringify(command));
+}
+
+// Handle response from device
+mqttClient.subscribe(`alteriom/nodes/${command.device_id}/responses`, (message) => {
+  const response = JSON.parse(message);
+  const respResult = validators.commandResponse(response);
+  
+  if (respResult.valid && isCommandResponseMessage(response)) {
+    if (response.correlation_id === command.correlation_id) {
+      if (response.success) {
+        console.log('Command succeeded:', response.result);
+        console.log(`Latency: ${response.latency_ms}ms`);
+      } else {
+        console.error(`Command failed: ${response.error_code} - ${response.message}`);
+      }
+    }
+  }
+});
+```
+
+**Command Pattern Features:**
+- Event-based discrimination (`event: "command"` and `event: "command_response"`)
+- Correlation IDs for request/response tracking
+- Command name validation (lowercase snake_case)
+- Flexible parameters object for command-specific data
+- Priority field for queue management
+- Success boolean and error codes in responses
+- Latency tracking for performance monitoring
+
+## Enhanced Location & Environment Tracking (v0.6.0+)
+
+Track device location and deployment context for asset management and map-based visualization:
+
+```ts
+import { validators, isSensorDataMessage } from '@alteriom/mqtt-schema';
+
+const sensorData = {
+  schema_version: 1,
+  device_id: 'SN456',
+  device_type: 'sensor',
+  timestamp: new Date().toISOString(),
+  firmware_version: 'SN 2.1.0',
+  // Standardized location for map visualization
+  location: {
+    latitude: 43.6532,
+    longitude: -79.3832,
+    altitude: 76.5,
+    accuracy_m: 10.0,
+    zone: 'warehouse_A',
+    description: 'Shelf 3, Row B'
+  },
+  // Deployment context
+  environment: {
+    deployment_type: 'indoor',
+    power_source: 'battery',
+    expected_battery_life_days: 365
+  },
+  sensors: {
+    temperature: {
+      value: 22.3,
+      unit: 'C',
+      // Enhanced sensor metadata
+      timestamp: '2025-10-19T20:59:58.000Z',
+      accuracy: 0.5,
+      last_calibration: '2025-01-15',
+      error_margin_pct: 2.0,
+      operational_range: { min: -40, max: 85 },
+      quality_score: 0.95
+    }
+  },
+  battery_level: 78,
+  signal_strength: -65
+};
+
+const result = validators.sensorData(sensorData);
+if (result.valid && isSensorDataMessage(sensorData)) {
+  // Display on map using location data
+  displayOnMap(sensorData.location.latitude, sensorData.location.longitude);
+  
+  // Show sensor health based on metadata
+  if (sensorData.sensors.temperature.accuracy) {
+    console.log(`Temperature accuracy: ±${sensorData.sensors.temperature.accuracy}${sensorData.sensors.temperature.unit}`);
+  }
+  
+  // Check calibration status
+  const lastCal = new Date(sensorData.sensors.temperature.last_calibration);
+  const daysSinceCalibration = (Date.now() - lastCal.getTime()) / (1000 * 60 * 60 * 24);
+  if (daysSinceCalibration > 365) {
+    console.warn('Sensor calibration overdue');
+  }
+}
+```
+
+**Location & Environment Features:**
+- GPS coordinates (latitude, longitude, altitude) with accuracy tracking
+- Zone-based organization (warehouses, floors, rooms)
+- Human-readable location descriptions
+- Deployment type tracking (indoor/outdoor/mobile)
+- Power source information for battery management
+- Per-sensor timestamps for async polling scenarios
+- Sensor accuracy and calibration tracking
+- Operational range validation support
+
+## Enhanced Gateway Metrics (v0.6.0+)
+
+Comprehensive system health monitoring for gateways:
+
+```ts
+import { validators, isGatewayMetricsMessage } from '@alteriom/mqtt-schema';
+
+const metrics = {
+  schema_version: 1,
+  device_id: 'GW002',
+  device_type: 'gateway',
+  timestamp: new Date().toISOString(),
+  firmware_version: 'GW 1.4.0',
+  metrics: {
+    uptime_s: 86400,
+    cpu_usage_pct: 15.3,
+    memory_usage_pct: 42.7,
+    temperature_c: 45.2,
+    // Enhanced storage metrics
+    storage_usage_pct: 45.2,
+    storage_total_mb: 512,
+    storage_free_mb: 280.5,
+    // Network bandwidth tracking
+    network_rx_kbps: 125.4,
+    network_tx_kbps: 89.3,
+    active_connections: 5,
+    // System health indicators
+    error_count_24h: 3,
+    warning_count_24h: 12,
+    restart_count: 2,
+    last_restart_reason: 'firmware_update',
+    // Mesh network metrics
+    connected_devices: 12,
+    mesh_nodes: 8,
+    packet_loss_pct: 0.5
+  }
+};
+
+const result = validators.gatewayMetrics(metrics);
+if (result.valid && isGatewayMetricsMessage(metrics)) {
+  // Storage monitoring
+  if (metrics.metrics.storage_usage_pct > 80) {
+    console.warn('Storage usage critical:', metrics.metrics.storage_usage_pct);
+  }
+  
+  // Network health
+  const totalBandwidth = metrics.metrics.network_rx_kbps + metrics.metrics.network_tx_kbps;
+  console.log(`Total bandwidth: ${totalBandwidth.toFixed(1)} kbps`);
+  
+  // Error trend analysis
+  if (metrics.metrics.error_count_24h > 10) {
+    console.error('High error rate detected:', metrics.metrics.error_count_24h);
+  }
+  
+  // Restart tracking
+  console.log(`Last restart: ${metrics.metrics.last_restart_reason}`);
+  console.log(`Total restarts: ${metrics.metrics.restart_count}`);
+}
+```
+
+**Enhanced Gateway Metrics Features:**
+- Storage usage tracking (percentage, total, free space)
+- Network bandwidth monitoring (RX/TX rates)
+- Active connection counting
+- Error and warning counters (24-hour rolling window)
+- Restart tracking with reason codes
+- All metrics are optional for gradual firmware adoption
+
 ## OTA Firmware Manifest Schema (v0.3.1+)
 
 The package includes OTA firmware manifest schema with both rich and minimal formats.
@@ -172,7 +375,9 @@ All Ajv validator functions are compiled once at module load. For typical web us
 | gateway_info.schema.json | Gateway identity & capabilities |
 | gateway_metrics.schema.json | Gateway performance metrics |
 | firmware_status.schema.json | Firmware update lifecycle events |
-| control_response.schema.json | Command/control response messages |
+| control_response.schema.json | Command/control response messages (deprecated, use command_response) |
+| **command.schema.json** | **Device control commands (v0.5.0+)** |
+| **command_response.schema.json** | **Command execution responses with correlation (v0.5.0+)** |
 | mesh_node_list.schema.json | Mesh network node list with status |
 | mesh_topology.schema.json | Mesh network topology and connections |
 | mesh_alert.schema.json | Mesh network alerts and warnings |
@@ -190,10 +395,12 @@ All Ajv validator functions are compiled once at module load. For typical web us
 
 ### Validator Keys
 
-`sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`, `meshNodeList`, `meshTopology`, `meshAlert`
+`sensorData`, `sensorHeartbeat`, `sensorStatus`, `gatewayInfo`, `gatewayMetrics`, `firmwareStatus`, `controlResponse`, `command`, `commandResponse`, `meshNodeList`, `meshTopology`, `meshAlert`
 
 ### Classification Heuristics (Simplified)
 
+- `event: "command"` → `command` (v0.5.0+)
+- `event: "command_response"` → `commandResponse` (v0.5.0+)
 - `metrics` → `gatewayMetrics`
 - `sensors` → `sensorData`
 - `nodes` array → `meshNodeList`

package/dist/cjs/generated/types.d.ts

@@ -1,9 +1,24 @@
 /**
  * Auto-generated TypeScript types for Alteriom MQTT Schema v1
  * Source: docs/mqtt_schema/*.schema.json
- * Generation Date: 2025-09-20
+ * Generation Date: 2025-10-19
  * NOTE: This file is maintained in firmware repo for UI alignment. Changes require coordinated review.
  */
+export interface LocationInfo {
+    latitude?: number;
+    longitude?: number;
+    altitude?: number;
+    accuracy_m?: number;
+    zone?: string;
+    description?: string;
+    [k: string]: unknown;
+}
+export interface EnvironmentInfo {
+    deployment_type?: 'indoor' | 'outdoor' | 'mobile' | 'mixed';
+    power_source?: 'battery' | 'mains' | 'solar' | 'mixed' | 'other';
+    expected_battery_life_days?: number;
+    [k: string]: unknown;
+}
 export interface BaseEnvelope {
     schema_version: 1;
     device_id: string;
@@ -11,6 +26,8 @@ export interface BaseEnvelope {
     timestamp: string;
     firmware_version?: string;
     hardware_version?: string;
+    location?: LocationInfo;
+    environment?: EnvironmentInfo;
     [k: string]: unknown;
 }
 export interface SensorEntry {
@@ -22,6 +39,14 @@ export interface SensorEntry {
     name?: string;
     location?: string;
     additional_data?: Record<string, unknown>;
+    timestamp?: string;
+    accuracy?: number;
+    last_calibration?: string;
+    error_margin_pct?: number;
+    operational_range?: {
+        min: number;
+        max: number;
+    };
     [k: string]: unknown;
 }
 export interface SensorDataMessage extends BaseEnvelope {
@@ -67,6 +92,16 @@ export interface GatewayMetricsMessage extends BaseEnvelope {
         mesh_nodes?: number;
         packet_loss_pct?: number;
         data_throughput_kbps?: number;
+        storage_usage_pct?: number;
+        storage_total_mb?: number;
+        storage_free_mb?: number;
+        network_rx_kbps?: number;
+        network_tx_kbps?: number;
+        active_connections?: number;
+        error_count_24h?: number;
+        warning_count_24h?: number;
+        restart_count?: number;
+        last_restart_reason?: string;
         [k: string]: unknown;
     };
 }
@@ -84,6 +119,26 @@ export interface ControlResponseMessage extends BaseEnvelope {
     message?: string;
     result?: unknown;
 }
+export interface CommandMessage extends BaseEnvelope {
+    firmware_version: string;
+    event: 'command';
+    command: string;
+    correlation_id?: string;
+    parameters?: Record<string, unknown>;
+    timeout_ms?: number;
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+}
+export interface CommandResponseMessage extends BaseEnvelope {
+    firmware_version: string;
+    event: 'command_response';
+    command?: string;
+    correlation_id?: string;
+    success: boolean;
+    result?: unknown;
+    message?: string;
+    error_code?: string;
+    latency_ms?: number;
+}
 export interface MeshNodeListMessage extends BaseEnvelope {
     device_type: 'gateway';
     firmware_version: string;
@@ -126,7 +181,7 @@ export interface MeshAlertMessage extends BaseEnvelope {
     }>;
     alert_count?: number;
 }
-export type AnyMqttV1Message = SensorDataMessage | SensorHeartbeatMessage | SensorStatusMessage | GatewayInfoMessage | GatewayMetricsMessage | FirmwareStatusMessage | ControlResponseMessage | MeshNodeListMessage | MeshTopologyMessage | MeshAlertMessage;
+export type AnyMqttV1Message = SensorDataMessage | SensorHeartbeatMessage | SensorStatusMessage | GatewayInfoMessage | GatewayMetricsMessage | FirmwareStatusMessage | ControlResponseMessage | CommandMessage | CommandResponseMessage | MeshNodeListMessage | MeshTopologyMessage | MeshAlertMessage;
 export declare function isSensorDataMessage(msg: any): msg is SensorDataMessage;
 export declare function isSensorHeartbeatMessage(msg: any): msg is SensorHeartbeatMessage;
 export declare function isSensorStatusMessage(msg: any): msg is SensorStatusMessage;
@@ -137,6 +192,8 @@ export declare function isControlResponseMessage(msg: any): msg is ControlRespon
 export declare function isMeshNodeListMessage(msg: any): msg is MeshNodeListMessage;
 export declare function isMeshTopologyMessage(msg: any): msg is MeshTopologyMessage;
 export declare function isMeshAlertMessage(msg: any): msg is MeshAlertMessage;
+export declare function isCommandMessage(msg: any): msg is CommandMessage;
+export declare function isCommandResponseMessage(msg: any): msg is CommandResponseMessage;
 export declare function classifyMessage(msg: any): AnyMqttV1Message | null;
 export interface BasicValidationIssue {
     field?: string;

package/dist/cjs/generated/types.js

@@ -2,7 +2,7 @@
 /**
  * Auto-generated TypeScript types for Alteriom MQTT Schema v1
  * Source: docs/mqtt_schema/*.schema.json
- * Generation Date: 2025-09-20
+ * Generation Date: 2025-10-19
  * NOTE: This file is maintained in firmware repo for UI alignment. Changes require coordinated review.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -16,6 +16,8 @@ exports.isControlResponseMessage = isControlResponseMessage;
 exports.isMeshNodeListMessage = isMeshNodeListMessage;
 exports.isMeshTopologyMessage = isMeshTopologyMessage;
 exports.isMeshAlertMessage = isMeshAlertMessage;
+exports.isCommandMessage = isCommandMessage;
+exports.isCommandResponseMessage = isCommandResponseMessage;
 exports.classifyMessage = classifyMessage;
 exports.basicValidate = basicValidate;
 exports.parseMessage = parseMessage;
@@ -50,6 +52,12 @@ function isMeshTopologyMessage(msg) {
 function isMeshAlertMessage(msg) {
     return msg && msg.schema_version === 1 && msg.device_type === 'gateway' && Array.isArray(msg.alerts);
 }
+function isCommandMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.event === 'command' && typeof msg.command === 'string';
+}
+function isCommandResponseMessage(msg) {
+    return msg && msg.schema_version === 1 && msg.event === 'command_response' && typeof msg.success === 'boolean';
+}
 function classifyMessage(msg) {
     if (isSensorDataMessage(msg))
         return msg;
@@ -61,6 +69,10 @@ function classifyMessage(msg) {
         return msg;
     if (isMeshAlertMessage(msg))
         return msg;
+    if (isCommandMessage(msg))
+        return msg;
+    if (isCommandResponseMessage(msg))
+        return msg;
     if (isSensorStatusMessage(msg))
         return msg;
     if (isGatewayInfoMessage(msg))

package/dist/cjs/schema_data.d.ts

@@ -32,6 +32,64 @@ export declare const envelope_schema: {
             readonly type: "string";
             readonly maxLength: 80;
         };
+        readonly location: {
+            readonly type: "object";
+            readonly description: "Standardized location information for geospatial tracking";
+            readonly properties: {
+                readonly latitude: {
+                    readonly type: "number";
+                    readonly minimum: -90;
+                    readonly maximum: 90;
+                };
+                readonly longitude: {
+                    readonly type: "number";
+                    readonly minimum: -180;
+                    readonly maximum: 180;
+                };
+                readonly altitude: {
+                    readonly type: "number";
+                    readonly description: "Altitude in meters";
+                };
+                readonly accuracy_m: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Position accuracy in meters";
+                };
+                readonly zone: {
+                    readonly type: "string";
+                    readonly maxLength: 64;
+                    readonly description: "Logical zone identifier (e.g., warehouse_A, floor_2)";
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly maxLength: 256;
+                    readonly description: "Human-readable location description";
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly environment: {
+            readonly type: "object";
+            readonly description: "Environmental and deployment context metadata";
+            readonly properties: {
+                readonly deployment_type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["indoor", "outdoor", "mobile", "mixed"];
+                    readonly description: "Type of deployment environment";
+                };
+                readonly power_source: {
+                    readonly type: "string";
+                    readonly enum: readonly ["battery", "mains", "solar", "mixed", "other"];
+                    readonly description: "Primary power source";
+                };
+                readonly expected_battery_life_days: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Expected battery life in days (if battery-powered)";
+                };
+            };
+            readonly additionalProperties: true;
+        };
     };
     readonly additionalProperties: true;
 };
@@ -78,6 +136,41 @@ export declare const sensor_data_schema: {
                     readonly additional_data: {
                         readonly type: "object";
                     };
+                    readonly timestamp: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                        readonly description: "Per-sensor reading timestamp (useful for async multi-sensor polling)";
+                    };
+                    readonly accuracy: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly description: "Sensor accuracy (±value in sensor units)";
+                    };
+                    readonly last_calibration: {
+                        readonly type: "string";
+                        readonly format: "date";
+                        readonly description: "Last calibration date (ISO 8601 date)";
+                    };
+                    readonly error_margin_pct: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                        readonly maximum: 100;
+                        readonly description: "Error margin as percentage";
+                    };
+                    readonly operational_range: {
+                        readonly type: "object";
+                        readonly description: "Valid operational range for this sensor";
+                        readonly required: readonly ["min", "max"];
+                        readonly properties: {
+                            readonly min: {
+                                readonly type: "number";
+                            };
+                            readonly max: {
+                                readonly type: "number";
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
                 };
                 readonly additionalProperties: false;
             };
@@ -237,6 +330,57 @@ export declare const gateway_metrics_schema: {
                     readonly type: "number";
                     readonly minimum: 0;
                 };
+                readonly storage_usage_pct: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 100;
+                    readonly description: "Disk/flash storage usage percentage";
+                };
+                readonly storage_total_mb: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Total storage capacity in megabytes";
+                };
+                readonly storage_free_mb: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Free storage space in megabytes";
+                };
+                readonly network_rx_kbps: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Network receive bandwidth in kilobits per second";
+                };
+                readonly network_tx_kbps: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Network transmit bandwidth in kilobits per second";
+                };
+                readonly active_connections: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Number of active network connections";
+                };
+                readonly error_count_24h: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Error count in last 24 hours";
+                };
+                readonly warning_count_24h: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Warning count in last 24 hours";
+                };
+                readonly restart_count: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Total restart counter since deployment";
+                };
+                readonly last_restart_reason: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                    readonly description: "Reason for last restart (e.g., watchdog, power_loss, update, manual)";
+                };
             };
             readonly additionalProperties: true;
         };
@@ -303,6 +447,122 @@ export declare const control_response_schema: {
     };
     readonly additionalProperties: true;
 };
+export declare const command_schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.alteriom.io/mqtt/v1/command.schema.json";
+    readonly title: "Device Command v1";
+    readonly description: "Command message sent from MQTT client to IoT device for control operations";
+    readonly allOf: readonly [{
+        readonly $ref: "envelope.schema.json";
+    }];
+    readonly type: "object";
+    readonly required: readonly ["event", "command"];
+    readonly properties: {
+        readonly event: {
+            readonly type: "string";
+            readonly const: "command";
+            readonly description: "Event type discriminator";
+        };
+        readonly command: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 64;
+            readonly pattern: "^[a-z][a-z0-9_]*$";
+            readonly description: "Command name in snake_case (e.g., read_sensors, set_interval, restart)";
+            readonly examples: readonly ["read_sensors", "set_interval", "enable_sensor", "update_config", "restart", "get_status"];
+        };
+        readonly correlation_id: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 128;
+            readonly pattern: "^[A-Za-z0-9_-]+$";
+            readonly description: "Unique identifier for tracking command → response lifecycle";
+        };
+        readonly parameters: {
+            readonly type: "object";
+            readonly description: "Command-specific parameters (validated by device)";
+            readonly additionalProperties: true;
+            readonly examples: readonly [{
+                readonly interval: 30000;
+            }, {
+                readonly sensor: "temperature";
+                readonly enabled: true;
+            }, {
+                readonly immediate: true;
+                readonly sensors: readonly ["temperature", "humidity"];
+            }];
+        };
+        readonly timeout_ms: {
+            readonly type: "integer";
+            readonly minimum: 1000;
+            readonly maximum: 300000;
+            readonly default: 5000;
+            readonly description: "Command execution timeout in milliseconds";
+        };
+        readonly priority: {
+            readonly type: "string";
+            readonly enum: readonly ["low", "normal", "high", "urgent"];
+            readonly default: "normal";
+            readonly description: "Command priority for queue management";
+        };
+    };
+    readonly additionalProperties: true;
+};
+export declare const command_response_schema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.alteriom.io/mqtt/v1/command_response.schema.json";
+    readonly title: "Command Response v1";
+    readonly description: "Response message from IoT device after executing a command";
+    readonly allOf: readonly [{
+        readonly $ref: "envelope.schema.json";
+    }];
+    readonly type: "object";
+    readonly required: readonly ["event", "success"];
+    readonly properties: {
+        readonly event: {
+            readonly type: "string";
+            readonly const: "command_response";
+            readonly description: "Event type discriminator";
+        };
+        readonly command: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 64;
+            readonly description: "Original command name that was executed";
+        };
+        readonly correlation_id: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 128;
+            readonly pattern: "^[A-Za-z0-9_-]+$";
+            readonly description: "Matches correlation_id from original command";
+        };
+        readonly success: {
+            readonly type: "boolean";
+            readonly description: "Whether command execution succeeded";
+        };
+        readonly result: {
+            readonly type: readonly ["object", "array", "string", "number", "boolean", "null"];
+            readonly description: "Command execution result data";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly maxLength: 256;
+            readonly description: "Human-readable status message";
+        };
+        readonly error_code: {
+            readonly type: "string";
+            readonly maxLength: 64;
+            readonly description: "Machine-readable error code (e.g., TIMEOUT, INVALID_PARAMS)";
+        };
+        readonly latency_ms: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "Time taken to execute command in milliseconds";
+        };
+    };
+    readonly additionalProperties: true;
+};
 export declare const mesh_node_list_schema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://schemas.alteriom.io/mqtt/v1/mesh_node_list.schema.json";
@@ -481,6 +741,8 @@ export declare const mqtt_v1_bundle_json: {
         readonly gateway_metrics: "gateway_metrics.schema.json";
         readonly firmware_status: "firmware_status.schema.json";
         readonly control_response: "control_response.schema.json";
+        readonly command: "command.schema.json";
+        readonly command_response: "command_response.schema.json";
         readonly mesh_node_list: "mesh_node_list.schema.json";
         readonly mesh_topology: "mesh_topology.schema.json";
         readonly mesh_alert: "mesh_alert.schema.json";