v4.12.0 — Phase 7: deferred init, hooks, flow control, skill composer, semantic search

jovanSAPFIONEER · jovanSAPFIONEER · commit 1edfc9205472 · 2026-04-01T15:21:18.000+02:00
Version bump to 4.12.0. Updated all docs: README badges, CHANGELOG,
SECURITY, CONTRIBUTING, ENTERPRISE, INTEGRATION_GUIDE, CLAUDE, CODEX,
copilot-instructions, adapter-system reference. 1,778 tests / 22 suites.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -4,8 +4,8 @@
 
 | Version | Supported |
 |---------|-----------|
-| 4.11.x  | ✅ Yes — full support (current) |
-| 4.10.x  | ✅ Security fixes only |
+| 4.12.x  | ✅ Yes — full support (current) |
+| 4.11.x  | ✅ Security fixes only |
 | 4.9.x   | ✅ Security fixes only |
 | 4.8.x   | ✅ Security fixes only |
 | 4.7.x   | ✅ Security fixes only |
@@ -41,6 +41,9 @@ Network-AI includes built-in security features:
 - **ComplianceMonitor** (v3.3.0) -- real-time agent behavior surveillance with configurable violation policies, severity classification, and async audit loop
 - **Named Multi-Blackboard API** (v3.4.0) -- isolated `SharedBlackboard` instances per name with independent namespaces, validation configs, and agent scoping; prevents cross-task data leakage
 - **QA Orchestrator Agent** (v4.11.0) -- scenario replay through quality gates, cross-agent contradiction detection, feedback loop with retry limits, and regression tracking with historical snapshots
+- **Deferred Adapter Initialization** (v4.12.0) -- adapters are materialized only on first use via `registerDeferred()`, preventing untrusted adapter code from running at startup
+- **Adapter Hook Middleware** (v4.12.0) -- `beforeExecute` / `afterExecute` / `onError` lifecycle hooks; enables request-level logging, tracing, and custom security gates without modifying adapters
+- **Flow Control** (v4.12.0) -- `pause()` / `resume()` / `setThrottle()` on the blackboard; prevents write floods and enables coordinated maintenance windows
 
 ## Security Scan Results
 
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination (v4.11.0). 1,684 tests across 21 suites.
+Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination (v4.12.0). 1,778 tests across 22 suites.
 
 ## Architecture
 
@@ -27,13 +27,16 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, gu
 - `lib/locked-blackboard.ts` — LockedBlackboard with atomic propose → validate → commit
 - `lib/fsm-journey.ts` — JourneyFSM behavioral control plane
 - `lib/compliance-monitor.ts` — Real-time agent behavior surveillance
+- `lib/adapter-hooks.ts` — AdapterHookManager lifecycle hooks
+- `lib/skill-composer.ts` — SkillComposer meta-operations (chain/batch/loop/verify)
+- `lib/semantic-search.ts` — SemanticMemory BYOE vector store
 - `adapters/` — 17 framework adapters (LangChain, AutoGen, CrewAI, MCP, Codex, MiniMax, NemoClaw, APS, etc.)
 
 ## Build & Test
 
 ```bash
 npx tsc --noEmit              # Type-check (zero errors expected)
-npm run test:all              # All 1,684 tests across 21 suites
+npm run test:all              # All 1,778 tests across 22 suites
 npm test                      # Core orchestrator tests
 npm run test:adapters         # All 17 adapters
 ```
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,27 @@ 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).
 
+## [4.12.0] - 2026-04-01
+
+### Added
+- **Deferred Adapter Initialization** — `registerDeferred(name, factory, config)` on `AdapterRegistry`; adapters are created and initialized only on first use via `resolveAdapterAsync()`. `executeAgent()` auto-materializes deferred adapters transparently. `listAdapters()` shows deferred entries with `deferred: true`.
+- **Adapter Hook Middleware** (`AdapterHookManager`) — lifecycle hooks (`beforeExecute` / `afterExecute` / `onError`) that wrap any adapter's `executeAgent` call. Priority-ordered execution, payload/result mutation, abort support. New module: `lib/adapter-hooks.ts`.
+- **Flow Control** on `LockedBlackboard` — `pause()` / `resume()` / `isPaused()` blocks writes/commits while paused (reads continue); `setThrottle(ms)` / `getThrottle()` enforces minimum interval between mutating operations; `throttleMs` option in constructor.
+- **Skill Composer** (`SkillComposer`) — `chain()`, `batch()`, `loop()`, `verify()` meta-operations for composing multi-agent workflows. Chain passes `previousResult` downstream; batch supports concurrency limits; loop has condition + maxIterations; verify retries until validator passes. New module: `lib/skill-composer.ts`.
+- **Semantic Memory Search** (`SemanticMemory`) — BYOE (bring your own embedding function) in-memory vector store with cosine similarity search, `topK` + `threshold`, `indexSnapshot()` for bulk blackboard import. New module: `lib/semantic-search.ts`.
+- `adapter:deferred` event type in `AdapterEventType`
+- `AdapterFactory` type export from adapter-registry
+- 94 new tests in `test-phase7.ts` (1,778 total across 22 suites)
+
+### Fixed
+- **CodeQL #91** — removed unused `badResult` variable in `test-qa.ts`
+- Constructor detection in `LockedBlackboard` now recognizes options with only `throttleMs` (without `conflictResolution`)
+
+### Changed
+- `AdapterRegistry.listAdapters()` return type now includes optional `deferred` field
+- `LockedBlackboardOptions` interface extended with `throttleMs` property
+- CI: bumped `github/codeql-action` from 4.34.1 to 4.35.1 (PR #79)
+
 ## [4.11.2] - 2026-03-22
 
 ### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,14 +4,14 @@ This file is read automatically by Claude Code when working in this repository.
 
 ## Project Overview
 
-Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 4.10.0.
+Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 4.12.0.
 
 ## Build & Test Commands
 
 ```bash
 npm install                   # Install dependencies
 npx tsc --noEmit              # Type-check (zero errors expected)
-npm run test:all              # Run all 1,684 tests across 21 suites
+npm run test:all              # Run all 1,778 tests across 22 suites
 npm test                      # Core orchestrator tests only
 npm run test:security         # Security module tests
 npm run test:adapters         # All 17 adapter tests
@@ -28,6 +28,9 @@ All tests must pass before any commit. No test should be skipped or marked `.onl
 - `lib/locked-blackboard.ts` — LockedBlackboard with atomic propose → validate → commit and file-system mutex
 - `lib/fsm-journey.ts` — JourneyFSM behavioral control plane
 - `lib/compliance-monitor.ts` — Real-time agent behavior surveillance
+- `lib/adapter-hooks.ts` — AdapterHookManager: beforeExecute/afterExecute/onError lifecycle hooks
+- `lib/skill-composer.ts` — SkillComposer: chain/batch/loop/verify meta-operations
+- `lib/semantic-search.ts` — SemanticMemory: BYOE vector store with cosine similarity
 - `adapters/` — 17 framework adapters (LangChain, AutoGen, CrewAI, MCP, Codex, MiniMax, NemoClaw, APS, etc.)
 - `bin/cli.ts` — CLI entry point (`npx network-ai`)
 - `bin/mcp-server.ts` — MCP server (SSE + stdio transport)
diff --git a/CODEX.md b/CODEX.md
@@ -4,14 +4,14 @@ This file is read automatically by OpenAI Codex CLI when working in this reposit
 
 ## Project Overview
 
-Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 4.10.0.
+Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 4.12.0.
 
 ## Build & Test Commands
 
 ```bash
 npm install                   # Install dependencies
 npx tsc --noEmit              # Type-check (zero errors expected)
-npm run test:all              # Run all 1,684 tests across 21 suites
+npm run test:all              # Run all 1,778 tests across 22 suites
 npm test                      # Core orchestrator tests only
 npm run test:security         # Security module tests
 npm run test:adapters         # All 17 adapter tests
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,7 +16,7 @@ Unsolicited PRs without a linked, approved issue will be closed.
 
 ### Code Quality
 
-- All 1,684 existing tests must pass (`npm run test:all`)
+- All 1,778 existing tests must pass (`npm run test:all`)
 - Zero TypeScript compile errors (`npx tsc --noEmit`)
 - New features must include tests with >90% branch coverage
 - Follow existing code style and patterns
@@ -78,7 +78,7 @@ Unsolicited PRs without a linked, approved issue will be closed.
 git clone https://github.com/Jovancoding/Network-AI.git
 cd Network-AI
 npm install
-npm run test:all  # Run all 1,684 tests (21 suites)
+npm run test:all  # Run all 1,778 tests (22 suites)
 npm run test:phase4  # Phase 4 behavioral control plane tests only
 npx tsc --noEmit  # Type-check
 ```
diff --git a/ENTERPRISE.md b/ENTERPRISE.md
@@ -100,7 +100,7 @@ Network-AI follows [Semantic Versioning](https://semver.org/):
 
 ### Stability Signals
 
-- 1,684 passing assertions across 21 suites
+- 1,778 passing assertions across 22 suites
 - Deterministic scoring — no random outcomes in permission evaluation or budget enforcement
 - CI runs on every push and every PR
 - All examples ship with the repo and run without mocking
diff --git a/INTEGRATION_GUIDE.md b/INTEGRATION_GUIDE.md
@@ -408,7 +408,8 @@ Run these before declaring the integration production-ready:
 - [ ] `npx ts-node test-adapters.ts` — 176 adapter tests pass
 - [ ] `npx ts-node test-phase4.ts` — 147 behavioral tests pass
 - [ ] `npx ts-node test-qa.ts` — 67 QA orchestrator tests pass
-- [ ] `npm run test:all` — all 1,684 tests pass across 21 suites
+- [ ] `npx ts-node test-phase7.ts` — 94 Phase 7 tests pass (hooks, flow control, composer, semantic search)
+- [ ] `npm run test:all` — all 1,778 tests pass across 22 suites
 - [ ] `npm run demo -- --08` runs to completion in < 10 seconds
 
 ### Race Condition Safety
diff --git a/README.md b/README.md
@@ -5,9 +5,9 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v4.11.2-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v4.12.0-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
-[![Tests](https://img.shields.io/badge/tests-1684%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-1778%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-17%20supported-blueviolet.svg)](#adapter-system)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Socket](https://socket.dev/api/badge/npm/package/network-ai)](https://socket.dev/npm/package/network-ai/overview)
@@ -89,6 +89,11 @@ Runs priority preemption, AuthGuardian permission gating, FSM governance, and co
 | ✅ FSM governance | Hard-stop agents at state boundaries, timeout enforcement |
 | ✅ Compliance monitoring | Real-time violation detection (tool abuse, turn-taking, timeouts) |
 | ✅ QA orchestration | Scenario replay, feedback loops, regression tracking, contradiction detection |
+| ✅ Deferred adapter init | Lazy-load adapters on first use — zero startup cost for unused frameworks |
+| ✅ Hook middleware | `beforeExecute` / `afterExecute` / `onError` hooks on any adapter call |
+| ✅ Flow control | Pause / resume / throttle writes on the blackboard |
+| ✅ Skill composition | `chain()` / `batch()` / `loop()` / `verify()` meta-operations over agent calls |
+| ✅ Semantic memory search | BYOE vector store with cosine similarity over blackboard data |
 | ✅ TypeScript native | ES2022 strict mode, zero native dependencies |
 
 ---
@@ -384,7 +389,7 @@ npm run test:priority     # Priority & preemption
 npm run test:cli          # CLI layer
 ```
 
-**1,684 passing assertions across 21 test suites** (`npm run test:all`):
+**1,778 passing assertions across 22 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
@@ -408,6 +413,7 @@ npm run test:cli          # CLI layer
 | `test-security.ts` | 34 | Tokens, sanitization, rate limiting, encryption, audit |
 | `test-cli.ts` | 65 | CLI layer: bb, auth, budget, audit commands |
 | `test-qa.ts` | 67 | QA orchestrator: scenarios, feedback loop, regression, contradictions |
+| `test-phase7.ts` | 94 | Deferred init, hook middleware, flow control, skill composer, semantic search |
 
 ---
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,8 +4,8 @@
 
 | Version | Supported |
 |---------|-----------||
-| 4.11.x  | ✅ Yes — full support (current) |
-| 4.10.x  | ✅ Security fixes only |
+| 4.12.x  | ✅ Yes — full support (current) |
+| 4.11.x  | ✅ Security fixes only |
 | 4.9.x   | ✅ Security fixes only |
 | 4.8.x   | ✅ Security fixes only |
 | 4.7.x   | ✅ Security fixes only |
@@ -41,6 +41,9 @@ Network-AI includes built-in security features:
 - **ComplianceMonitor** (v3.3.0) -- real-time agent behavior surveillance with configurable violation policies, severity classification, and async audit loop
 - **Named Multi-Blackboard API** (v3.4.0) -- isolated `SharedBlackboard` instances per name with independent namespaces, validation configs, and agent scoping; prevents cross-task data leakage
 - **QA Orchestrator Agent** (v4.11.0) -- scenario replay through quality gates, cross-agent contradiction detection, feedback loop with retry limits, and regression tracking with historical snapshots
+- **Deferred Adapter Initialization** (v4.12.0) -- adapters are materialized only on first use via `registerDeferred()`, preventing untrusted adapter code from running at startup
+- **Adapter Hook Middleware** (v4.12.0) -- `beforeExecute` / `afterExecute` / `onError` lifecycle hooks; enables request-level logging, tracing, and custom security gates without modifying adapters
+- **Flow Control** (v4.12.0) -- `pause()` / `resume()` / `setThrottle()` on the blackboard; prevents write floods and enables coordinated maintenance windows
 
 ## Security Scan Results
 
diff --git a/openapi.yaml b/openapi.yaml
@@ -6,7 +6,7 @@ info:
     blackboard coordination, parallel agent spawning, and permission gating
     via AuthGuardian. Requires the companion MCP server:
     `npm install -g network-ai && npx network-ai-server --port 3001`
-  version: 4.11.2
+  version: 4.12.0
   license:
     name: MIT
     url: https://github.com/Jovancoding/Network-AI/blob/main/LICENSE
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "4.11.2",
+  "version": "4.12.0",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 17 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://network-ai.org",
   "main": "dist/index.js",
diff --git a/references/adapter-system.md b/references/adapter-system.md
@@ -356,3 +356,91 @@ The adapter system is additive — everything from v1/v2 is preserved:
 - **Budget tracking** — unchanged
 - **Handoff protocol** — unchanged
 - **OpenClaw skill interface** — `SwarmOrchestrator` still implements `OpenClawSkill`
+
+## Deferred Adapter Initialization (v4.12.0)
+
+Register adapters lazily so they are only created and initialized on first use:
+
+```typescript
+import { AdapterRegistry, LangChainAdapter } from 'network-ai';
+
+const registry = new AdapterRegistry();
+
+// Factory is NOT called until the adapter is actually needed
+registry.registerDeferred('langchain', () => new LangChainAdapter(), {
+  autoInit: true,              // call initialize() after construction (default true)
+  initOptions: { model: 'gpt-4o' },
+});
+
+// Shows up in listings with deferred: true
+const list = registry.listAdapters();
+// → [{ name: 'langchain', deferred: true }]
+
+// First executeAgent or resolveAdapterAsync triggers materialization
+const adapter = await registry.resolveAdapterAsync('langchain');
+// Factory runs → initialize() called → adapter cached for reuse
+
+// executeAgent auto-resolves deferred adapters transparently
+const result = await registry.executeAgent('lc:research', payload, context);
+```
+
+- `registerDeferred(name, factory, config?)` — register a lazy factory
+- `resolveAdapterAsync(name)` — explicitly materialize a deferred adapter
+- `executeAgent()` — auto-materializes deferred adapters on demand
+- Emits `adapter:deferred` event when a deferred adapter is first materialized
+
+## Adapter Hook Middleware (v4.12.0)
+
+Wrap any adapter's `executeAgent` with lifecycle hooks:
+
+```typescript
+import { AdapterHookManager } from 'network-ai';
+
+const hooks = new AdapterHookManager();
+
+// beforeExecute — inspect or mutate payload, or abort
+hooks.beforeExecute(async (ctx) => {
+  console.log(`Executing ${ctx.agentId} on ${ctx.adapterName}`);
+  // Mutate payload:  ctx.payload.handoff.instruction = 'modified';
+  // Abort execution: return { abort: true, reason: 'blocked' };
+}, { priority: 10 });
+
+// afterExecute — inspect or mutate result
+hooks.afterExecute(async (ctx) => {
+  ctx.result.metadata.hookedAt = Date.now();
+}, { priority: 10 });
+
+// onError — handle or rethrow errors
+hooks.onError(async (ctx) => {
+  console.error(`Error in ${ctx.agentId}:`, ctx.error);
+  // Optionally return a fallback result
+});
+
+// Wrap an adapter
+const wrappedExecute = hooks.wrap(adapter);
+const result = await wrappedExecute('research', payload, context);
+```
+
+Hooks run in priority order (lower = first). Multiple hooks per phase are supported. `beforeExecute` hooks can abort by returning `{ abort: true, reason }`.
+
+## Flow Control on LockedBlackboard (v4.12.0)
+
+Pause, resume, and throttle write operations on the blackboard:
+
+```typescript
+import { LockedBlackboard } from 'network-ai';
+
+const bb = new LockedBlackboard({ throttleMs: 200 });
+
+// Pause — blocks propose() and commit() while paused; read() still works
+bb.pause();
+bb.isPaused();  // true
+bb.resume();
+
+// Throttle — enforces minimum ms between mutating operations
+bb.setThrottle(500);  // 500ms between writes
+bb.getThrottle();     // 500
+
+// Constructor option
+const bb2 = new LockedBlackboard({ throttleMs: 100, conflictResolution: 'last-write-wins' });
+```
diff --git a/skill.json b/skill.json
@@ -1,6 +1,6 @@
 {
   "name": "SwarmOrchestrator",
-  "version": "4.11.2",
+  "version": "4.12.0",
   "description": "Local Python orchestration skill: multi-agent workflows via shared blackboard file, permission gating, token budget scripts, and persistent project context. The bundled Python scripts make no network calls and have zero third-party dependencies. Workflow delegations via the host platform's sessions_send may invoke external model APIs.",
   "author": "Network-AI Community",
   "homepage": "https://network-ai.org",
