Ruflo Agent Swarm                          Cognitum Device Fleet
=================                          =====================

[Fleet Manager Agent]                      [Seed A] ---- mesh ---- [Seed B]
       |                                       |                       |
       v                                       |                       |
[Device Coordinator]                           |                       |
       |                                       |                       |
       +--- SeedClient(A) ----- mTLS ---------+                       |
       |                                                               |
       +--- SeedClient(B) ----- mTLS ---------------------------------+
       |
       v
[Telemetry Analyzer Agent]
       |
       v
[AgentDB / HNSW]
  - device state snapshots
  - telemetry patterns
  - anomaly signatures
  - firmware history

Cognitum Seed Device                      Ruflo Plugin                        AgentDB
====================                      ============                        =======

[Sensor Data]
    |
    v
[On-device Vector Store]
    |
    v                                 [SeedClient.store.query()]
[store.query() response] ----------> [Telemetry Ingest Pipeline]
                                          |
                                          v
                                     [Anomaly Detection]
                                          |          |
                                          v          v
                                     [Alert Hook]  [HNSW Index]
                                          |          |
                                          v          v
                                     [Agent Swarm] [Pattern Store]
                                     (remediation)  (learning)


[OTA Update Available]
    |
    v                                 [SeedClient.ota.checkNow()]
[ota.checkNow() response] ---------> [Firmware Orchestrator]
                                          |
                                          v
                                     [Staged Rollout Engine]
                                          |
                                     [Canary Check] -----> [Rollback Gate]
                                          |                      |
                                          v                      v
                                     [Fleet OTA Sweep]    [Rollback All]


[Witness Chain]
    |
    v                                 [SeedClient.witness.chain()]
[witness.chain() response] --------> [Provenance Verifier]
                                          |
                                          v
                                     [Audit Service]
                                          |
                                          v
                                     [AgentDB: iot-audit namespace]

/**
 * A Cognitum Seed device registered with the Ruflo agent system.
 * Wraps the SDK's SeedClient and exposes device resources as agent capabilities.
 */
interface DeviceAgent {
  deviceId: string;                    // From SeedIdentity.device_id
  publicKey: string;                   // Ed25519 public key from identity()
  firmwareVersion: string;             // Current firmware version
  trustLevel: DeviceTrustLevel;        // IoT-adapted trust level
  trustScore: number;                  // Continuous score 0.0-1.0
  fleetId: string;                     // Logical fleet grouping
  zoneId: string;                      // IEC 62443 security zone
  status: DeviceStatus;                // online | offline | updating | quarantined
  lastSeen: Date;                      // Last successful heartbeat
  epoch: number;                       // Custody epoch for state sync
  capabilities: DeviceCapability[];    // Available device capabilities
  meshPeers: string[];                 // Known mesh peer device IDs
  vectorStoreStats: StoreStatus;       // On-device vector store metrics
  metadata: Record<string, unknown>;   // Extensible metadata
}

type DeviceStatus = 'online' | 'offline' | 'updating' | 'quarantined' | 'decommissioned';

type DeviceCapability =
  | 'vector-store'       // Has HNSW vector store
  | 'ota-update'         // Supports OTA firmware
  | 'mesh-routing'       // Participates in mesh network
  | 'witness-chain'      // Maintains Ed25519 witness chain
  | 'sensor-telemetry'   // Produces telemetry data
  | 'edge-compute'       // WASM runtime available
  | 'mcp-server';        // Exposes MCP tools

/**
 * A logical grouping of devices managed as a unit.
 * Maps to a Ruflo swarm with hierarchical topology.
 */
interface DeviceFleet {
  fleetId: string;
  name: string;
  description: string;
  zoneId: string;                      // IEC 62443 zone
  deviceIds: string[];
  firmwarePolicy: FirmwarePolicy;
  telemetryPolicy: TelemetryPolicy;
  healthThresholds: HealthThresholds;
  topology: FleetTopology;
  createdAt: Date;
  updatedAt: Date;
}

/**
 * A telemetry reading from a device, stored as a vector in AgentDB.
 */
interface TelemetryReading {
  readingId: string;
  deviceId: string;
  fleetId: string;
  timestamp: Date;
  vector: number[];                    // Embedding of telemetry data
  rawMetrics: Record<string, number>;  // Raw sensor values
  anomalyScore: number;                // 0.0 (normal) - 1.0 (anomalous)
  metadata: Record<string, unknown>;
}

/**
 * A firmware deployment operation targeting one or more devices.
 */
interface FirmwareDeployment {
  deploymentId: string;
  fleetId: string;
  targetVersion: string;
  currentVersion: string;
  strategy: DeploymentStrategy;
  status: DeploymentStatus;
  stages: DeploymentStage[];
  startedAt: Date;
  completedAt?: Date;
  rollbackTriggered: boolean;
  deviceResults: Map<string, DeviceDeploymentResult>;
}

type DeploymentStrategy = 'canary' | 'rolling' | 'blue-green' | 'all-at-once';
type DeploymentStatus = 'pending' | 'canary' | 'rolling' | 'completed' | 'rolled-back' | 'failed';

enum DeviceTrustLevel {
  UNKNOWN = 0,        // Device seen but not paired
  REGISTERED = 1,     // Paired via pair.create(), identity verified
  PROVISIONED = 2,    // Firmware verified, policies applied, zone assigned
  CERTIFIED = 3,      // Extended uptime, clean witness chain, anomaly-free
  FLEET_TRUSTED = 4,  // Fleet-level attestation, institutional endorsement
}

interface DeviceTrustScore {
  overall: number;              // 0.0 - 1.0
  components: {
    pairingIntegrity: number;   // Pairing token validity, auth success rate
    firmwareCurrency: number;   // 1.0 if latest, decays with version lag
    uptimeStability: number;    // Uptime ratio over rolling window
    witnessIntegrity: number;   // Witness chain length / expected length
    anomalyHistory: number;     // 1.0 - (anomaly rate over rolling window)
    meshParticipation: number;  // Active mesh peer count / expected peers
  };
}

interface FirmwarePolicy {
  channel: string;                        // 'stable' | 'beta' | 'canary'
  autoUpdate: boolean;                    // Allow automatic updates
  approvalRequired: boolean;              // Human approval gate
  canaryPercentage: number;               // % of fleet for canary stage
  canaryDurationMinutes: number;          // How long canary runs before rollout
  rollbackOnAnomalyThreshold: number;     // Anomaly score that triggers rollback
  maintenanceWindow?: { start: string; end: string }; // ISO time window
}

interface TelemetryPolicy {
  ingestionIntervalSeconds: number;       // How often to pull telemetry
  retentionDays: number;                  // How long to keep in AgentDB
  anomalyDetectionEnabled: boolean;       // Run SONA anomaly detection
  anomalyThreshold: number;              // Score threshold for alerting
  vectorDimension: number;                // Embedding dimension for store
}

interface HealthThresholds {
  maxOfflineMinutes: number;              // Before quarantine
  minUptimeRatio: number;                 // Over rolling 24h window
  maxConsecutiveAnomalies: number;        // Before auto-quarantine
  minFirmwareCurrency: number;            // Min firmware version lag
}

type FleetTopology = 'star' | 'mesh' | 'hierarchical' | 'ring';

/**
 * Manages device lifecycle: registration, pairing, health monitoring,
 * and decommissioning. Wraps SeedClient instances per device.
 */
interface DeviceLifecycleService {
  registerDevice(endpoint: string, fleetId: string): Promise<DeviceAgent>;
  pairDevice(deviceId: string, clientName: string): Promise<PairCreateResponse>;
  unpairDevice(deviceId: string, clientName: string): Promise<void>;
  heartbeat(deviceId: string): Promise<DeviceAgent>;
  quarantineDevice(deviceId: string, reason: string): Promise<void>;
  decommissionDevice(deviceId: string): Promise<void>;
  getDeviceStatus(deviceId: string): Promise<DeviceAgent>;
}

/**
 * Ingests telemetry from device vector stores, runs anomaly detection,
 * and stores patterns in AgentDB for SONA learning.
 */
interface TelemetryIngestionService {
  ingestFromDevice(deviceId: string, queryVector: number[], k: number): Promise<TelemetryReading[]>;
  batchIngest(fleetId: string): Promise<TelemetryReading[]>;
  detectAnomalies(readings: TelemetryReading[]): Promise<AnomalyDetection[]>;
  storePattern(pattern: TelemetryPattern): Promise<void>;
  queryPatterns(query: string, limit?: number): Promise<TelemetryPattern[]>;
}

/**
 * Orchestrates firmware deployments across device fleets with staged
 * rollout, canary verification, and automatic rollback.
 */
interface FirmwareOrchestrationService {
  checkUpdates(fleetId: string): Promise<Map<string, DeviceUpdateCheck>>;
  deployFirmware(fleetId: string, strategy: DeploymentStrategy): Promise<FirmwareDeployment>;
  advanceStage(deploymentId: string): Promise<FirmwareDeployment>;
  rollback(deploymentId: string, reason: string): Promise<FirmwareDeployment>;
  getDeploymentStatus(deploymentId: string): Promise<FirmwareDeployment>;
}

/**
 * Manages device fleet topology, mapping device mesh networks
 * to Ruflo swarm topologies.
 */
interface FleetTopologyService {
  createFleet(config: Omit<DeviceFleet, 'fleetId' | 'createdAt' | 'updatedAt'>): Promise<DeviceFleet>;
  addDeviceToFleet(deviceId: string, fleetId: string): Promise<void>;
  removeDeviceFromFleet(deviceId: string, fleetId: string): Promise<void>;
  getFleetTopology(fleetId: string): Promise<FleetTopologyMap>;
  syncMeshTopology(fleetId: string): Promise<void>;
  getFleetHealth(fleetId: string): Promise<FleetHealthReport>;
}

/**
 * Verifies witness chains for cryptographic provenance and
 * integrates with Ruflo's audit service.
 */
interface WitnessVerificationService {
  verifyChain(deviceId: string): Promise<WitnessVerification>;
  getProvenance(deviceId: string, sinceEpoch?: number): Promise<WitnessEntry[]>;
  exportAuditTrail(fleetId: string, format: 'json' | 'csv'): Promise<string>;
}

interface IoTCoordinatorConfig {
  cognitumApiKey?: string;             // For cloud control plane
  cloudBaseUrl?: string;               // Default: api.cognitum.one
  discoveryMode: 'explicit' | 'mdns' | 'tailscale' | 'mixed';
  defaultFleetTopology: FleetTopology;
  defaultFirmwarePolicy: FirmwarePolicy;
  defaultTelemetryPolicy: TelemetryPolicy;
  defaultHealthThresholds: HealthThresholds;
  tls: {
    ca?: string | Buffer;
    insecure?: boolean;                // Dev-only
  };
}

class IoTCoordinator {
  constructor(
    config: IoTCoordinatorConfig,
    deviceLifecycle: DeviceLifecycleService,
    telemetry: TelemetryIngestionService,
    firmware: FirmwareOrchestrationService,
    fleetTopology: FleetTopologyService,
    witness: WitnessVerificationService,
    trustEvaluator: DeviceTrustEvaluator,
    auditService: IoTAuditService,
  );

  // Lifecycle
  async initialize(): Promise<void>;
  async shutdown(): Promise<void>;
  getStatus(): IoTCoordinatorStatus;

  // Device operations (delegated to services)
  async registerDevice(endpoint: string, fleetId: string): Promise<DeviceAgent>;
  async queryDeviceTelemetry(deviceId: string, vector: number[], k: number): Promise<TelemetryReading[]>;
  async deployFirmware(fleetId: string, strategy: DeploymentStrategy): Promise<FirmwareDeployment>;
  async getFleetHealth(fleetId: string): Promise<FleetHealthReport>;
  async verifyWitnessChain(deviceId: string): Promise<WitnessVerification>;
}

/**
 * Trust score formula for devices:
 *
 *   trust_score = 0.20 * pairing_integrity
 *               + 0.20 * firmware_currency
 *               + 0.15 * uptime_stability
 *               + 0.15 * witness_integrity
 *               + 0.15 * anomaly_history
 *               + 0.15 * mesh_participation
 *
 * Weights reflect IoT-specific priorities: identity and firmware
 * are critical; mesh participation matters for fleet coherence.
 */

interface DeviceTrustTransitionThresholds {
  '0->1': { condition: 'pair.create() succeeds' };
  '1->2': { upgradeScore: 0.65; minUptimeHours: 24; firmwareVerified: true };
  '2->3': { upgradeScore: 0.80; minUptimeHours: 168; witnessChainLength: 100; anomalyRate: 0.02 };
  '3->4': { upgradeScore: 0.92; institutionalAttestation: true; minFleetMembers: 5 };
}

// Automatic downgrade triggers (immediate, no hysteresis):
// - 3 consecutive auth failures (inherits SDK trust-score 3-strike cutoff)
// - Firmware hash mismatch detected in witness chain
// - Anomaly score > 0.9 sustained for > 5 minutes
// - Mesh partition lasting > 30 minutes with no heartbeat
// - TLS fingerprint mismatch (inherits SDK TlsPinError)

interface AnomalyDetection {
  readingId: string;
  deviceId: string;
  score: number;                       // 0.0 - 1.0
  type: AnomalyType;
  confidence: number;
  baselinePattern?: string;            // AgentDB pattern key
  suggestedAction: AnomalyAction;
  metadata: Record<string, unknown>;
}

type AnomalyType =
  | 'drift'              // Gradual deviation from baseline
  | 'spike'              // Sudden value change
  | 'flatline'           // No variance (sensor failure?)
  | 'oscillation'        // Rapid fluctuation
  | 'pattern-break'      // Breaks learned periodic pattern
  | 'cluster-outlier';   // Outlier relative to fleet cluster

type AnomalyAction =
  | 'log'                // Below threshold, log only
  | 'alert'              // Notify fleet manager agent
  | 'quarantine'         // Isolate device from fleet
  | 'recalibrate'        // Trigger sensor recalibration
  | 'rollback-firmware'  // Suspect firmware regression
  | 'human-review';      // Escalate to operator

/**
 * Factory that creates and manages SeedClient instances per device/fleet.
 * Handles discovery provider selection, TLS configuration, and token management.
 */
class SeedClientFactory {
  constructor(config: IoTCoordinatorConfig);

  /**
   * Create a SeedClient for a single device endpoint.
   * Uses the SDK's mesh-aware routing when multiple endpoints are provided.
   */
  async createClient(
    endpoints: string | string[],
    options?: Partial<SeedClientOptions>,
  ): Promise<SeedClient>;

  /**
   * Create a SeedClient using mDNS discovery for LAN-local seeds.
   * Requires optional peer dependency: multicast-dns
   */
  async createMdnsClient(
    options?: Partial<SeedClientOptions>,
  ): Promise<SeedClient>;

  /**
   * Create a SeedClient using Tailscale discovery for overlay networks.
   */
  async createTailscaleClient(
    options?: Partial<SeedClientOptions>,
  ): Promise<SeedClient>;

  /**
   * Close all managed clients. Called during plugin shutdown.
   */
  async closeAll(): Promise<void>;
}

/**
 * Cloud control plane client for fleet-level operations.
 * Wraps the Cognitum class from @cognitum-one/sdk (main export).
 */
class CloudControlPlane {
  private readonly cognitum: Cognitum;

  constructor(config: CognitumConfig);

  async registerDevice(params: DeviceRegisterParams): Promise<void>;
  async checkUpdate(deviceId: string): Promise<DeviceUpdateCheck>;
  async heartbeat(deviceId: string): Promise<void>;
  async getFleetStatus(): Promise<FleetStatus>;
  async health(): Promise<HealthResponse>;

  // Brain knowledge base for fleet patterns
  async sharePattern(params: BrainShareParams): Promise<BrainMemory>;
  async searchPatterns(query: string): Promise<BrainSearchResult>;

  // MCP tool proxy
  async listMcpTools(): Promise<McpTool[]>;
  async callMcpTool(name: string, args?: Record<string, unknown>): Promise<McpToolCallResult>;
}

// AgentDB namespaces used by the IoT plugin:
const IOT_NAMESPACES = {
  DEVICES: 'iot-devices',              // DeviceAgent state
  FLEETS: 'iot-fleets',               // DeviceFleet configurations
  TELEMETRY: 'iot-telemetry',          // TelemetryReading vectors (HNSW-indexed)
  ANOMALY_PATTERNS: 'iot-anomalies',   // Learned anomaly signatures
  FIRMWARE: 'iot-firmware',            // FirmwareDeployment records
  AUDIT: 'iot-audit',                  // IoT-specific audit events
  WITNESS: 'iot-witness',             // Witness chain snapshots
  TRUST: 'iot-trust',                  // Device trust score history
} as const;

/**
 * Telemetry vectors are stored with HNSW indexing for fast similarity search.
 * This enables: "find all readings similar to this anomalous reading" in <10ms.
 */
interface TelemetryRepository {
  store(reading: TelemetryReading): Promise<void>;
  batchStore(readings: TelemetryReading[]): Promise<void>;
  querySimilar(vector: number[], k: number, fleetId?: string): Promise<TelemetryReading[]>;
  queryByDevice(deviceId: string, since: Date, limit: number): Promise<TelemetryReading[]>;
  queryByAnomalyScore(threshold: number, limit: number): Promise<TelemetryReading[]>;
  prune(olderThan: Date): Promise<number>;
}

/**
 * Device state repository. Stores DeviceAgent snapshots with
 * trust score history for trend analysis.
 */
interface DeviceRepository {
  upsert(device: DeviceAgent): Promise<void>;
  get(deviceId: string): Promise<DeviceAgent | null>;
  listByFleet(fleetId: string): Promise<DeviceAgent[]>;
  listByStatus(status: DeviceStatus): Promise<DeviceAgent[]>;
  listByTrustLevel(level: DeviceTrustLevel): Promise<DeviceAgent[]>;
  getTrustHistory(deviceId: string, days: number): Promise<DeviceTrustScore[]>;
  delete(deviceId: string): Promise<void>;
}

/**
 * Adapts Cognitum SDK's transport (undici-based HTTP + TLS) for use
 * within the Ruflo plugin context. Handles:
 * - SeedClient construction with proper TLS config
 * - Per-peer cert pinning via mDNS fp= records
 * - TokenBook management (pairing tokens per peer)
 * - Health probe coordination with Ruflo's health check system
 */
class CognitumTransport {
  private readonly factory: SeedClientFactory;
  private readonly clients: Map<string, SeedClient>;       // fleetId -> SeedClient
  private readonly tokenBooks: Map<string, TokenBook>;     // fleetId -> TokenBook

  async connect(fleetId: string, endpoints: string[]): Promise<void>;
  async disconnect(fleetId: string): Promise<void>;
  async getClient(fleetId: string): Promise<SeedClient>;

  // Mesh topology sync
  async syncMeshState(fleetId: string): Promise<MeshStatus>;
  async getPeers(fleetId: string): Promise<MeshPeers>;

  // Health monitoring
  async probeHealth(fleetId: string): Promise<Map<string, PeerState>>;
}

Trust Level 0: UNKNOWN        -- Device endpoint discovered but not paired
Trust Level 1: REGISTERED     -- pair.create() succeeded, Ed25519 identity verified
Trust Level 2: PROVISIONED    -- Firmware verified, policies applied, zone assigned
Trust Level 3: CERTIFIED      -- Extended clean operation, witness chain verified
Trust Level 4: FLEET_TRUSTED  -- Institutional attestation, fleet-level endorsement

device_trust_score = 0.20 * pairing_integrity
                   + 0.20 * firmware_currency
                   + 0.15 * uptime_stability
                   + 0.15 * witness_integrity
                   + 0.15 * anomaly_history
                   + 0.15 * mesh_participation

type IoTClaimType =
  | 'iot:device:discover'         // Can discover devices via mDNS/explicit
  | 'iot:device:register'         // Can register (pair) new devices
  | 'iot:device:status'           // Can read device status and identity
  | 'iot:device:telemetry:read'   // Can query device vector stores
  | 'iot:device:telemetry:write'  // Can ingest vectors into device stores
  | 'iot:device:quarantine'       // Can quarantine a device
  | 'iot:device:decommission'     // Can decommission (unpair + remove)
  | 'iot:fleet:manage'            // Can create/modify fleets
  | 'iot:fleet:deploy'            // Can trigger fleet-wide deployments
  | 'iot:firmware:check'          // Can check for firmware updates
  | 'iot:firmware:deploy'         // Can deploy firmware to individual devices
  | 'iot:firmware:fleet-deploy'   // Can deploy firmware fleet-wide (high risk)
  | 'iot:firmware:rollback'       // Can rollback firmware
  | 'iot:witness:read'            // Can query witness chains
  | 'iot:admin'                   // Full IoT plugin administration
  ;

interface ZoneCrossingPolicy {
  sourceZone: string;
  targetZone: string;
  allowed: boolean;
  minTrustLevel: DeviceTrustLevel;
  requirePiiScan: boolean;          // Strip PII from cross-zone telemetry
  requireAuditLog: boolean;         // Log every cross-zone operation
  rateLimit: number;                // Max operations per minute
}

iot_device_register
  Description: Register a new Cognitum Seed device with the Ruflo agent system
  Input:
    endpoint: string    (required) -- Device HTTPS endpoint (e.g., https://cognitum.local:8443)
    fleetId: string     (required) -- Fleet to assign device to
    clientName: string  (optional) -- Client name for pairing (default: ruflo-{timestamp})
    zoneId: string      (optional) -- IEC 62443 security zone
  Output: DeviceAgent JSON with deviceId, trustLevel, capabilities

iot_device_status
  Description: Get comprehensive device status including trust score, store stats, and mesh state
  Input:
    deviceId: string    (required) -- Device ID to query
    detailed: boolean   (optional) -- Include trust score breakdown and witness chain summary
  Output: DeviceAgent JSON with current state

iot_device_pair
  Description: Pair with a Cognitum Seed device (requires open pairing window on device)
  Input:
    deviceId: string    (required) -- Device ID to pair with
    clientName: string  (required) -- Human-readable client name for this pairing
  Output: Pairing status with redacted token confirmation

iot_device_unpair
  Description: Revoke pairing with a device
  Input:
    deviceId: string    (required) -- Device ID to unpair
    clientName: string  (required) -- Client name to revoke
  Output: Confirmation of pairing revocation

iot_device_quarantine
  Description: Quarantine a device, isolating it from fleet operations
  Input:
    deviceId: string    (required) -- Device ID to quarantine
    reason: string      (required) -- Reason for quarantine (audit trail)
  Output: Updated DeviceAgent with quarantined status

iot_device_decommission
  Description: Permanently decommission a device (requires human authority)
  Input:
    deviceId: string    (required) -- Device ID to decommission
    reason: string      (required) -- Reason for decommission
    force: boolean      (optional) -- Skip graceful shutdown (emergency only)
  Output: Decommission confirmation with audit event ID

iot_fleet_create
  Description: Create a new device fleet with topology, firmware, and telemetry policies
  Input:
    name: string                   (required) -- Fleet name
    description: string            (optional) -- Fleet description
    zoneId: string                 (optional) -- IEC 62443 security zone
    topology: string               (optional) -- star | mesh | hierarchical | ring (default: hierarchical)
    firmwareChannel: string        (optional) -- stable | beta | canary (default: stable)
    telemetryInterval: number      (optional) -- Seconds between telemetry pulls (default: 60)
  Output: DeviceFleet JSON

iot_fleet_status
  Description: Get fleet health including device statuses, anomaly summary, and firmware versions
  Input:
    fleetId: string    (required) -- Fleet ID to query
  Output: FleetHealthReport JSON

iot_fleet_topology
  Description: Get the fleet's mesh topology as seen from the device network layer
  Input:
    fleetId: string    (required) -- Fleet ID
  Output: Topology map with device connections, latencies, and health states

iot_fleet_discover
  Description: Discover Cognitum Seed devices on the local network via mDNS
  Input:
    timeoutMs: number  (optional) -- Discovery timeout in ms (default: 5000)
    fleetId: string    (optional) -- Auto-assign discovered devices to this fleet
  Output: Array of discovered device endpoints with device IDs and TLS fingerprints

iot_telemetry_query
  Description: Query a device's on-board vector store for telemetry readings
  Input:
    deviceId: string    (required) -- Device ID to query
    vector: number[]    (required) -- Query vector for similarity search
    k: number           (optional) -- Number of results (default: 10)
    metric: string      (optional) -- cosine | euclidean | dot (default: cosine)
  Output: StoreQueryResponse with nearest telemetry readings

iot_telemetry_ingest
  Description: Ingest telemetry vectors into a device's on-board vector store
  Input:
    deviceId: string           (required) -- Target device ID
    vectors: StoreIngestItem[] (required) -- Vectors with optional metadata
  Output: StoreIngestResponse with ingest count and witness chain update

iot_telemetry_anomalies
  Description: Run anomaly detection on recent telemetry from a fleet
  Input:
    fleetId: string     (required) -- Fleet to analyze
    threshold: number   (optional) -- Anomaly score threshold (default: 0.7)
    limit: number       (optional) -- Max results (default: 50)
  Output: Array of AnomalyDetection with scores, types, and suggested actions

iot_telemetry_baseline
  Description: Compute or update the telemetry baseline for a fleet (used by SONA anomaly detection)
  Input:
    fleetId: string     (required) -- Fleet to baseline
    windowDays: number  (optional) -- Historical window for baseline (default: 7)
  Output: Baseline statistics with per-device and fleet-aggregate patterns

iot_firmware_check
  Description: Check for available firmware updates across a fleet
  Input:
    fleetId: string    (required) -- Fleet to check
  Output: Map of deviceId -> DeviceUpdateCheck with version info

iot_firmware_deploy
  Description: Deploy firmware to a fleet using a staged rollout strategy
  Input:
    fleetId: string         (required) -- Target fleet
    strategy: string        (optional) -- canary | rolling | blue-green | all-at-once (default: canary)
    canaryPercentage: number (optional) -- Canary stage percentage (default: 10)
    canaryDuration: number  (optional) -- Canary duration in minutes (default: 30)
  Output: FirmwareDeployment with deployment ID and stage details

iot_firmware_rollback
  Description: Rollback a firmware deployment
  Input:
    deploymentId: string   (required) -- Deployment to rollback
    reason: string         (required) -- Reason for rollback
  Output: Updated FirmwareDeployment with rollback status

iot_firmware_status
  Description: Get the status of a firmware deployment
  Input:
    deploymentId: string   (required) -- Deployment ID
  Output: FirmwareDeployment with per-device results

iot_witness_verify
  Description: Verify a device's Ed25519 witness chain for cryptographic integrity
  Input:
    deviceId: string    (required) -- Device ID
    sinceEpoch: number  (optional) -- Start from this epoch
  Output: WitnessVerification with chain integrity status and any gaps

iot_audit_query
  Description: Query IoT audit logs with filtering
  Input:
    eventType: string   (optional) -- Filter by event type
    deviceId: string    (optional) -- Filter by device
    fleetId: string     (optional) -- Filter by fleet
    severity: string    (optional) -- info | warn | error | critical
    since: string       (optional) -- ISO 8601 start date
    limit: number       (optional) -- Max results (default: 50)
  Output: Array of IoTAuditEvent

iot_trust_review
  Description: Review device trust score with component breakdown
  Input:
    deviceId: string    (required) -- Device ID
  Output: DeviceTrustScore with component breakdown and trend

iot init                                    # Initialize IoT plugin with Cognitum API key and default policies
iot device register <endpoint>              # Register a Seed device by endpoint
  --fleet <fleetId>                         #   Assign to fleet (required)
  --zone <zoneId>                           #   IEC 62443 security zone
  --client-name <name>                      #   Pairing client name
iot device list                             # List all registered devices
  --fleet <fleetId>                         #   Filter by fleet
  --status <status>                         #   Filter by status
  --trust-level <level>                     #   Filter by trust level (0-4)
  --format <table|json>                     #   Output format
iot device status <deviceId>                # Show device status with trust score
  --detailed                                #   Include trust breakdown and witness summary
iot device quarantine <deviceId>            # Quarantine a device
  --reason <reason>                         #   Reason (required)
iot device decommission <deviceId>          # Decommission a device (requires authority)
  --reason <reason>                         #   Reason (required)
  --force                                   #   Skip graceful shutdown
iot device discover                         # Discover devices via mDNS
  --timeout <ms>                            #   Discovery timeout (default 5000)
  --auto-register <fleetId>                 #   Auto-register to fleet

iot fleet create <name>                     # Create a new device fleet
  --zone <zoneId>                           #   Security zone
  --topology <type>                         #   star | mesh | hierarchical | ring
  --firmware-channel <channel>              #   stable | beta | canary
iot fleet list                              # List all fleets
  --format <table|json>                     #   Output format
iot fleet status <fleetId>                  # Fleet health report
  --detailed                                #   Include per-device breakdown
iot fleet topology <fleetId>                # Show fleet mesh topology
  --format <ascii|json|dot>                 #   Output format (ascii=visual, dot=graphviz)
iot fleet add-device <fleetId> <deviceId>   # Add device to fleet
iot fleet remove-device <fleetId> <deviceId> # Remove device from fleet

iot telemetry query <deviceId>              # Query device vector store
  --vector <json>                           #   Query vector (JSON array)
  --k <number>                              #   Number of results (default 10)
  --metric <cosine|euclidean|dot>           #   Distance metric
iot telemetry anomalies <fleetId>           # Run anomaly detection
  --threshold <number>                      #   Score threshold (default 0.7)
  --since <date>                            #   Start date
iot telemetry baseline <fleetId>            # Compute telemetry baseline
  --window <days>                           #   Historical window (default 7)

iot firmware check <fleetId>                # Check for firmware updates
iot firmware deploy <fleetId>               # Deploy firmware
  --strategy <canary|rolling|blue-green|all-at-once>
  --canary-pct <number>                     #   Canary percentage (default 10)
  --canary-duration <minutes>               #   Canary duration (default 30)
  --dry-run                                 #   Preview without deploying
iot firmware rollback <deploymentId>        # Rollback deployment
  --reason <reason>                         #   Reason (required)
iot firmware status <deploymentId>          # Deployment status
  --format <table|json>                     #   Output format

iot witness verify <deviceId>               # Verify witness chain
  --since-epoch <number>                    #   Start epoch
iot witness export <fleetId>                # Export witness audit trail
  --format <json|csv>                       #   Export format

iot audit                                   # Query audit logs
  --device <deviceId>                       #   Filter by device
  --fleet <fleetId>                         #   Filter by fleet
  --severity <level>                        #   Filter severity
  --since <date>                            #   Start date
  --export <json|csv|ndjson>                #   Export format
  --compliance <iec62443|nist-iot|none>     #   Compliance mode

iot trust <deviceId>                        # Review device trust
  --review                                  #   Show score breakdown
  --history <days>                          #   Show trust history

iot config                                  # View IoT plugin configuration
  --set-api-key <key>                       #   Set Cognitum API key
  --set-firmware-policy <path>              #   Set firmware policy JSON
  --set-telemetry-policy <path>             #   Set telemetry policy JSON
  --compliance <iec62443|nist-iot|none>     #   Set compliance mode

{
  type: 'iot-device-coordinator',
  name: 'IoT Device Coordinator',
  description: 'Manages device lifecycle: registration, pairing, health monitoring, trust evaluation, and decommissioning. Coordinates device agents within a fleet.',
  defaultConfig: {
    capabilities: [
      'iot:device:discover', 'iot:device:register', 'iot:device:status',
      'iot:device:quarantine', 'iot:device:decommission',
      'iot:fleet:manage', 'iot:trust:evaluate',
    ],
    maxConcurrentTasks: 20,
    priority: 90,
    timeout: 300_000,
  },
  requiredCapabilities: ['iot:device:discover', 'iot:device:register'],
  metadata: { trustAware: true, meshAware: true },
}

{
  type: 'iot-fleet-manager',
  name: 'IoT Fleet Manager',
  description: 'Manages fleet topology, policy enforcement, cross-fleet coordination, and fleet-level health assessment. Maps Cognitum mesh topology to Ruflo swarm topology.',
  defaultConfig: {
    capabilities: [
      'iot:fleet:manage', 'iot:fleet:deploy',
      'iot:device:status', 'iot:device:telemetry:read',
    ],
    maxConcurrentTasks: 10,
    priority: 85,
    timeout: 600_000,
  },
  requiredCapabilities: ['iot:fleet:manage'],
  metadata: { topologyAware: true, complianceAware: true },
}

{
  type: 'iot-edge-deployer',
  name: 'IoT Edge Deployer',
  description: 'Orchestrates firmware deployments with staged rollout, canary verification, anomaly-gated progression, and automatic rollback. Ensures firmware integrity via witness chain verification.',
  defaultConfig: {
    capabilities: [
      'iot:firmware:check', 'iot:firmware:deploy',
      'iot:firmware:fleet-deploy', 'iot:firmware:rollback',
      'iot:witness:read',
    ],
    maxConcurrentTasks: 5,
    priority: 95,    // High priority -- firmware ops are time-sensitive
    timeout: 1_800_000, // 30 minutes for fleet deployments
  },
  requiredCapabilities: ['iot:firmware:deploy'],
  metadata: { deploymentAware: true, rollbackCapable: true },
}

{
  type: 'iot-telemetry-analyzer',
  name: 'IoT Telemetry Analyzer',
  description: 'Ingests telemetry from device vector stores, runs SONA-powered anomaly detection, learns baseline patterns, and triggers remediation workflows when anomalies exceed thresholds.',
  defaultConfig: {
    capabilities: [
      'iot:device:telemetry:read', 'iot:device:telemetry:write',
      'iot:device:status',
    ],
    maxConcurrentTasks: 15,
    priority: 80,
    timeout: 120_000,
  },
  requiredCapabilities: ['iot:device:telemetry:read'],
  metadata: { sonaEnabled: true, hnswEnabled: true, anomalyDetection: true },
}

{
  type: 'iot-witness-auditor',
  name: 'IoT Witness Auditor',
  description: 'Periodically verifies device witness chains for integrity, detects chain gaps or signature failures, and produces compliance audit reports for IEC 62443 and NIST IoT.',
  defaultConfig: {
    capabilities: [
      'iot:witness:read', 'iot:device:status',
    ],
    maxConcurrentTasks: 10,
    priority: 75,
    timeout: 300_000,
  },
  requiredCapabilities: ['iot:witness:read'],
  metadata: { complianceAware: true, auditCapable: true },
}

Fleet Level (Ruflo hierarchical swarm)
|
+-- [Fleet Manager Agent] ---- coordinates fleet-level operations
|       |
|       +-- [Device Coordinator Agent] ---- manages device lifecycle
|       |       |
|       |       +-- [DeviceAgent: Seed-A] ---- trust level 3
|       |       +-- [DeviceAgent: Seed-B] ---- trust level 2
|       |       +-- [DeviceAgent: Seed-C] ---- trust level 1
|       |
|       +-- [Telemetry Analyzer Agent] ---- processes telemetry
|       |
|       +-- [Edge Deployer Agent] ---- manages firmware
|       |
|       +-- [Witness Auditor Agent] ---- verifies chains

Device Mesh Level (Cognitum mesh)
|
+-- [Seed-A] ---- mesh ---- [Seed-B] ---- mesh ---- [Seed-C]
     peer_count: 2            peer_count: 2            peer_count: 1

[Multi-Fleet Coordinator] ---- hierarchical-mesh topology
      |
      +-- [Fleet: Warehouse-A] ---- hierarchical
      |       +-- 50 devices
      |
      +-- [Fleet: Warehouse-B] ---- hierarchical
      |       +-- 30 devices
      |
      +-- [Fleet: Office-HQ] ---- star
              +-- 10 devices

Edge Installation (on-premise)          Cloud Installation
============================            ==================

[Fleet Manager Agent]                   [Cloud Coordinator Agent]
       |                                         |
       +-- 50 Seed devices                       |
       |                                         |
       v                                         v
[Federation Plugin]                     [Federation Plugin]
       |                                         |
       +---- mTLS federation session ------------+
       |
       v
  PII Pipeline strips device telemetry before
  crossing trust boundary. Only anomaly
  signatures and fleet health summaries cross.

v3/@claude-flow/plugin-iot-cognitum/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts                           # Plugin entry point
    plugin.ts                          # IoTCognitumPlugin class (ClaudeFlowPlugin)
    mcp-tools.ts                       # MCP tool definitions (18 tools)
    cli-commands.ts                    # CLI command definitions (30+ commands)

    domain/
      entities/
        device-agent.ts                # DeviceAgent entity
        device-fleet.ts                # DeviceFleet entity
        telemetry-reading.ts           # TelemetryReading entity
        firmware-deployment.ts         # FirmwareDeployment entity
        device-trust-level.ts          # DeviceTrustLevel value object
      services/
        device-lifecycle-service.ts    # Device registration, pairing, health
        telemetry-ingestion-service.ts # Telemetry pull, anomaly detection
        firmware-orchestration-service.ts # Staged firmware deployment
        fleet-topology-service.ts      # Fleet management, mesh sync
        witness-verification-service.ts # Witness chain verification
      repositories/
        device-repository.ts           # Device persistence interface
        fleet-repository.ts            # Fleet persistence interface
        telemetry-repository.ts        # Telemetry persistence interface
        firmware-repository.ts         # Firmware deployment persistence
        audit-repository.ts            # IoT audit persistence

    application/
      iot-coordinator.ts               # Orchestrates all IoT operations
      device-trust-evaluator.ts        # Device trust scoring
      anomaly-detection-engine.ts      # SONA-powered anomaly detection
      firmware-rollout-engine.ts       # Staged rollout state machine

    infrastructure/
      cognitum/
        seed-client-factory.ts         # SeedClient creation and management
        cloud-control-plane.ts         # Cognitum Cloud API wrapper
        discovery-adapter.ts           # Adapts SDK discovery to Ruflo
      persistence/
        agentdb-device-repository.ts   # AgentDB-backed device storage
        agentdb-fleet-repository.ts    # AgentDB-backed fleet storage
        agentdb-telemetry-repository.ts # AgentDB-backed telemetry (HNSW)
        agentdb-firmware-repository.ts # AgentDB-backed firmware records
        agentdb-audit-repository.ts    # AgentDB-backed audit storage
      transport/
        mesh-bridge.ts                 # Bridges Cognitum mesh to Ruflo swarm
        health-probe-adapter.ts        # Adapts SDK health probes to workers

    api/
      hooks.ts                         # Hook registrations (10 hooks)
      workers.ts                       # Background worker definitions (8 workers)

  __tests__/
    unit/
      device-lifecycle-service.test.ts
      telemetry-ingestion-service.test.ts
      firmware-orchestration-service.test.ts
      device-trust-evaluator.test.ts
      anomaly-detection-engine.test.ts
      witness-verification-service.test.ts
    integration/
      device-registration-flow.test.ts
      firmware-deployment-flow.test.ts
      telemetry-anomaly-flow.test.ts
      fleet-topology-sync.test.ts
    acceptance/
      iot-compliance-iec62443.test.ts
      iot-compliance-nist.test.ts

export class IoTCognitumPlugin implements ClaudeFlowPlugin {
  readonly name = '@claude-flow/plugin-iot-cognitum';
  readonly version = '1.0.0-alpha.1';
  readonly description = 'Cognitum Seed IoT device fleet management with agent-device duality';
  readonly author = 'Claude Flow Team';
  readonly dependencies = ['@claude-flow/security', '@claude-flow/memory'];

  readonly permissions: PluginPermissions = {
    network: true,       // SeedClient HTTP/TLS connections
    memory: true,        // AgentDB for telemetry, device state
    mcp: true,           // MCP tool registration
    agents: true,        // Agent type registration
  };

  readonly trustLevel: PluginTrustLevel = 'official';

  async initialize(context: PluginContext): Promise<void> {
    // 1. Read config: API key, discovery mode, TLS settings
    // 2. Initialize SeedClientFactory
    // 3. Initialize CloudControlPlane (if API key provided)
    // 4. Create domain services
    // 5. Create IoTCoordinator
    // 6. Register IoT claim types with @claude-flow/claims
    // 7. Register hooks and background workers
    // 8. Register CLI commands and MCP tools
    // 9. Start health probe worker
  }

  async shutdown(): Promise<void> {
    // 1. Stop all background workers
    // 2. Close all SeedClient connections
    // 3. Flush remaining telemetry to AgentDB
    // 4. Ship remaining audit logs
  }

  registerMCPTools(): MCPToolDefinition[] { /* 18 tools */ }
  registerCLICommands(): CLICommandDefinition[] { /* 30+ commands */ }
  registerAgentTypes(): AgentTypeDefinition[] { /* 5 agent types */ }
  async healthCheck(): Promise<boolean> { /* coordinator status */ }
}

{
  "name": "@claude-flow/plugin-iot-cognitum",
  "version": "1.0.0-alpha.1",
  "description": "Cognitum Seed IoT device fleet management for Claude Flow",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@cognitum-one/sdk": "^0.2.1",
    "@claude-flow/shared": "workspace:*",
    "@claude-flow/security": "workspace:*",
    "@claude-flow/memory": "workspace:*"
  },
  "peerDependencies": {
    "multicast-dns": "^7.2.5"
  },
  "peerDependenciesMeta": {
    "multicast-dns": {
      "optional": true
    }
  },
  "devDependencies": {
    "@types/node": "^25.6.0",
    "typescript": "^5.4.0",
    "vitest": "^2.0.0"
  },
  "engines": {
    "node": ">=18"
  },
  "license": "MIT",
  "keywords": [
    "claude-flow",
    "cognitum",
    "iot",
    "seed",
    "fleet-management",
    "device-management",
    "mcp",
    "ai-agents"
  ]
}

Setup:
  - Fleet A: 10 Seed devices (simulated), firmware v1.0, healthy baseline
  - Fleet B: 5 Seed devices (simulated), firmware v1.0, healthy baseline
  - 1 device in Fleet A will be injected with anomalous telemetry
  - 1 device in Fleet A will receive firmware v2.0 (canary)

Phase 1: Baseline Establishment
  - All 15 devices produce telemetry for 10 minutes (simulated time)
  - Baseline computed for both fleets
  - Verify: all devices reach trust level PROVISIONED (2)
  - Verify: anomaly scores < 0.3 for all devices

Phase 2: Anomaly Injection
  - Device A-7 produces anomalous telemetry (spike + drift)
  - Verify: anomaly detected within 2 scan intervals
  - Verify: iot-anomaly-detected hook fires
  - Verify: device A-7 quarantined automatically
  - Verify: fleet A health report shows 9/10 healthy
  - Verify: device A-7 trust score drops below downgrade threshold

Phase 3: Canary Firmware Deploy
  - Deploy firmware v2.0 to Fleet A with canary strategy (10% = 1 device)
  - Verify: only 1 device (A-1) receives update
  - Verify: pre-iot-deploy hook validates trust levels
  - Device A-1 produces healthy telemetry post-update
  - Verify: canary stage advances after configured duration
  - Rolling deployment proceeds to remaining healthy devices (8, excluding quarantined A-7)
  - Verify: all 8 devices report firmware v2.0
  - Verify: witness chains updated with firmware change entries

Phase 4: Firmware Regression Detection
  - Device A-3 (post-update) starts producing anomalous telemetry
  - Verify: firmware regression detected by SONA pattern comparison
  - Verify: rollback triggered for device A-3
  - Verify: A-3 returns to firmware v1.0
  - Verify: audit trail contains complete deployment + rollback record

Phase 5: Witness Chain Integrity
  - Verify: all device witness chains are contiguous
  - Verify: witness.chain() entries match expected epoch sequence
  - Verify: compliance audit for IEC 62443 FR3 (integrity) passes

Pass criteria: All verify statements pass.