feat: Phase 3 - Priority & Preemption (v3.2.0)

- Add ConflictResolutionStrategy type: 'first-commit-wins' | 'priority-wins'
- Add AgentPriority type (0-3) with validation/clamping
- Update propose() with optional priority parameter
- Update validate() to preempt lower-priority changes in priority-wins mode
- Update commit() with under-lock priority check
- Add findConflictingPendingChanges() and preempt() helpers
- Add BLACKBOARD_PREEMPT audit events
- Backward-compatible constructor overloads
- 64 new tests (13 test groups), 315 total passing
- Export new types from main index

Author: jovanSAPFIONEER

CHANGELOG.md

@@ -5,12 +5,26 @@ 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).
 
-## [Unreleased] -- Phase 3: Priority & Preemption
+## [3.2.0] - 2026-02-17
+
+### Added -- Phase 3: Priority & Preemption
+- **Priority-Based Conflict Resolution** -- `'priority-wins'` strategy for `LockedBlackboard` commit step; higher-priority agents preempt lower-priority pending/committed writes on same-key conflicts (0=low, 3=critical)
+- **`ConflictResolutionStrategy` type** -- Choose between `'first-commit-wins'` (default, current behavior) and `'priority-wins'` (new)
+- **`AgentPriority` type** -- `0 | 1 | 2 | 3` typed priority levels
+- **`LockedBlackboardOptions` interface** -- Configuration object for LockedBlackboard constructor
+- **Priority-aware `propose()`** -- Optional 5th parameter for agent priority
+- **Priority-aware `validate()`** -- In `priority-wins` mode, higher-priority changes preempt lower-priority pending changes and override committed values from lower-priority agents
+- **Priority-aware `commit()`** -- Under-lock double-check respects priority in `priority-wins` mode
+- **`findConflictingPendingChanges()`** -- Public helper to list pending/validated changes targeting the same key
+- **`getConflictResolution()`** -- Query the active conflict resolution strategy
+- **Preemption audit events** -- `BLACKBOARD_PREEMPT` events logged when changes are preempted
+- **Priority validation** -- Invalid priority values clamped to 0-3 range; non-integers default to 0
+- **Backward-compatible constructor** -- Supports both `new LockedBlackboard(path, auditLogger, options)` and `new LockedBlackboard(path, options)`
+- **64 new priority tests** -- 13 test groups covering default behavior regression, preemption, same-priority fallback, metadata, constructor overloads, TTL interaction, backward compatibility
 
-### Planned
-- **Priority-Based Conflict Resolution** -- `'priority-wins'` strategy for `LockedBlackboard` commit step; higher-priority agents preempt lower-priority pending writes on same-key conflicts (0=low, 3=critical)
-- **`ConflictResolutionStrategy` option** -- Choose between `'first-commit-wins'` (default, current behavior) and `'priority-wins'` (new)
-- **Priority-aware `validate()` / `commit()`** -- Wire `HandoffMessage.metadata.priority` into the atomic commit pipeline
+### Stats
+- 315 tests passing (79 + 33 + 139 + 64)
+- 0 compile errors
 
 ## [Future] -- Phase 4: Distributed Blackboard
 

README.md

@@ -2,14 +2,14 @@
 
 **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.1.3-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v3.2.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![ClawHub](https://img.shields.io/badge/ClawHub-network--ai-orange.svg)](https://clawhub.ai/skills/network-ai)
 [![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)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![AgentSkills](https://img.shields.io/badge/AgentSkills-compatible-orange.svg)](https://agentskills.io)
-[![Tests](https://img.shields.io/badge/tests-251%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-315%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-12%20supported-blueviolet.svg)](#adapter-system)
 [![RSS Feed](https://img.shields.io/badge/RSS-releases-orange?logo=rss)](https://github.com/jovanSAPFIONEER/Network-AI/releases.atom)
 
@@ -134,6 +134,7 @@ Network-AI wraps your agent swarm with **file-system mutexes**, **atomic commits
 ### Operational Safety
 - **Swarm Guard** -- Prevents "Handoff Tax" (wasted tokens) and detects silent agent failures
 - **Atomic Commits** -- File-system mutexes prevent split-brain in concurrent writes
+- **Priority-Based Preemption** -- Higher-priority agents preempt lower-priority writes on same-key conflicts (`priority-wins` strategy)
 - **Cost Awareness** -- Token budget tracking with automatic SafetyShutdown
 - **Budget-Aware Handoffs** -- `intercept-handoff` command wraps `sessions_send` with budget checks
 
@@ -358,7 +359,32 @@ python scripts/blackboard.py commit "chg_001"
 python scripts/blackboard.py list
 ```
 
-#### 5. Check Budget Status
+#### 5. Priority-Based Conflict Resolution (Phase 3)
+
+```typescript
+import { LockedBlackboard } from 'network-ai';
+
+// Enable priority-wins strategy
+const board = new LockedBlackboard('.', { conflictResolution: 'priority-wins' });
+
+// Low-priority worker proposes a change
+const lowId = board.propose('shared:config', { mode: 'draft' }, 'worker', undefined, 1);
+
+// High-priority supervisor proposes to same key
+const highId = board.propose('shared:config', { mode: 'final' }, 'supervisor', undefined, 3);
+
+// Worker commits first
+board.validate(lowId, 'orchestrator');
+board.commit(lowId);
+
+// Supervisor validates -- higher priority wins despite stale hash
+board.validate(highId, 'orchestrator'); // true (preempts worker's value)
+board.commit(highId);                   // success
+
+board.read('shared:config'); // { mode: 'final' } -- supervisor wins
+```
+
+#### 6. Check Budget Status
 
 ```bash
 python scripts/swarm_guard.py budget-check --task-id "task_001"

index.ts

@@ -15,6 +15,7 @@ import { randomUUID, createHmac } from 'crypto';
 import { AdapterRegistry } from './adapters/adapter-registry';
 import { InputSanitizer, SecureSwarmGateway, RateLimiter, SecureAuditLogger, DataEncryptor, SecurityError } from './security';
 import { LockedBlackboard } from './lib/locked-blackboard';
+import type { ConflictResolutionStrategy, AgentPriority, LockedBlackboardOptions } from './lib/locked-blackboard';
 import { BlackboardValidator, QualityGateAgent } from './lib/blackboard-validator';
 import { Logger } from './lib/logger';
 import {
@@ -2153,6 +2154,9 @@ export type {
 // Backward-compatible OpenClaw types
 export type { OpenClawSkill, SkillContext, SkillResult };
 
+// Phase 3: Priority & Preemption types
+export type { ConflictResolutionStrategy, AgentPriority, LockedBlackboardOptions };
+
 // Logger
 export { Logger, LogLevel } from './lib/logger';
 export type { LogEntry, LogTransport, LoggerConfig } from './lib/logger';