v3.1.0: Phase 2 - Trust (structured logging, typed errors, input validation, JSDoc, audit integration)

Author: jovanSAPFIONEER

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to Network-AI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-02-16
+
+### Added -- Phase 2: Trust
+- **Structured Logging** -- `Logger` class with 4 severity levels (DEBUG/INFO/WARN/ERROR) + SILENT, module-scoped instances via `Logger.create()`, pluggable transports
+- **Typed Error Hierarchy** -- `NetworkAIError` base class + 10 specific error subclasses (`AdapterError`, `BlackboardError`, `SecurityError`, `ValidationError`, `LockError`, `TimeoutError`, `PermissionError`, `ConfigurationError`, `AgentError`, `OrchestratorError`)
+- **Runtime API Input Validation** -- Guards on 20+ public entry points (`SwarmOrchestrator`, `SharedBlackboard`, `AuthGuardian`, `TaskDecomposer`, `AdapterRegistry`) with descriptive `ValidationError` throws
+- **Comprehensive JSDoc** -- Documentation on all exported interfaces (12+), classes (13+), and public methods (8+) with `@example`, `@param`, `@returns`, `@throws` tags
+- **Unified Lock + Audit Integration** -- `LockedBlackboard` now accepts an optional `SecureAuditLogger`; `write()` and `delete()` emit structured audit events (lock holder, duration, key, version, success/failure)
+
+### Stats
+- 251 tests passing (79 + 33 + 139)
+- 0 compile errors
+
 ## [3.0.3] - 2026-02-15
 
 ### Security Fix

README.md

@@ -2,7 +2,7 @@
 
 **The plug-and-play AI agent orchestrator for TypeScript/Node.js -- connect 12 agent frameworks with zero glue code**
 
-[![Release](https://img.shields.io/badge/release-v3.0.3-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v3.1.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://typescriptlang.org)
 [![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://python.org)

adapters/adapter-registry.ts

@@ -22,7 +22,29 @@ import type {
   AdapterEventHandler,
   AdapterEventType,
 } from '../types/agent-adapter';
+import { AdapterAlreadyRegisteredError, AdapterNotFoundError, ValidationError } from '../lib/errors';
 
+/**
+ * Central registry that manages multiple agent framework adapters and
+ * routes execution requests to the correct one.
+ *
+ * Supports pattern-based routing, automatic prefix detection, default
+ * adapter fallback, agent caching, unified discovery, and lifecycle events.
+ *
+ * @example
+ * ```typescript
+ * import { AdapterRegistry, LangChainAdapter, CustomAdapter } from 'network-ai';
+ *
+ * const registry = new AdapterRegistry();
+ * await registry.addAdapter(new LangChainAdapter());
+ * await registry.addAdapter(new CustomAdapter());
+ *
+ * // Route by prefix: "lc:research" -> LangChainAdapter
+ * registry.addRoute({ pattern: 'lc:*', adapterName: 'langchain' });
+ *
+ * const result = await registry.executeAgent('lc:research', payload, context);
+ * ```
+ */
 export class AdapterRegistry {
   private adapters: Map<string, IAgentAdapter> = new Map();
   private routes: AdapterRoute[] = [];
@@ -46,8 +68,14 @@ export class AdapterRegistry {
    * Call this for each agent framework you want to support.
    */
   registerAdapter(adapter: IAgentAdapter): void {
+    if (!adapter || typeof adapter !== 'object') {
+      throw new ValidationError('adapter is required and must be an object');
+    }
+    if (typeof adapter.name !== 'string' || adapter.name.trim() === '') {
+      throw new ValidationError('adapter.name must be a non-empty string');
+    }
     if (this.adapters.has(adapter.name)) {
-      throw new Error(`Adapter "${adapter.name}" is already registered`);
+      throw new AdapterAlreadyRegisteredError(adapter.name);
     }
     this.adapters.set(adapter.name, adapter);
     this.emit('adapter:registered', adapter.name);
@@ -57,9 +85,12 @@ export class AdapterRegistry {
    * Initialize a registered adapter with its configuration
    */
   async initializeAdapter(adapterName: string, config: AdapterConfig = {}): Promise<void> {
+    if (!adapterName || typeof adapterName !== 'string') {
+      throw new ValidationError('adapterName must be a non-empty string');
+    }
     const adapter = this.adapters.get(adapterName);
     if (!adapter) {
-      throw new Error(`Adapter "${adapterName}" is not registered`);
+      throw new AdapterNotFoundError(adapterName);
     }
     await adapter.initialize(config);
     this.emit('adapter:initialized', adapterName);
@@ -112,7 +143,7 @@ export class AdapterRegistry {
    */
   setDefaultAdapter(adapterName: string): void {
     if (!this.adapters.has(adapterName)) {
-      throw new Error(`Adapter "${adapterName}" is not registered`);
+      throw new AdapterNotFoundError(adapterName);
     }
     this.defaultAdapterName = adapterName;
   }

adapters/base-adapter.ts

@@ -17,6 +17,7 @@ import type {
   AgentResult,
   AgentInfo,
 } from '../types/agent-adapter';
+import { AdapterNotInitializedError } from '../lib/errors';
 
 export abstract class BaseAdapter implements IAgentAdapter {
   abstract readonly name: string;
@@ -135,7 +136,7 @@ export abstract class BaseAdapter implements IAgentAdapter {
    */
   protected ensureReady(): void {
     if (!this.ready) {
-      throw new Error(`Adapter "${this.name}" is not initialized. Call initialize() first.`);
+      throw new AdapterNotInitializedError(this.name);
     }
   }
 }