network-ai 3.6.2 → 3.7.1

package/dist/lib/blackboard-backend-crdt.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * CRDT Blackboard Backend
+ *
+ * Provides a `CrdtBackend` implementation of `BlackboardBackend` that uses
+ * vector clocks and conflict-free merge semantics to synchronize state across
+ * multiple nodes (processes or machines) without requiring coordination.
+ *
+ * Each `CrdtBackend` instance represents one "node" in the distributed system.
+ * Nodes exchange `CrdtEntry` records and merge them using `mergeEntry()` to
+ * converge to the same state — even after concurrent, offline writes.
+ *
+ * Architecture:
+ *   - Each node has a unique `nodeId` and a local `VectorClock`.
+ *   - Writes increment the node's own clock counter and tag the entry.
+ *   - Deletes record tombstones (`deleted: true`) so deletions propagate.
+ *   - `merge(entries)` applies conflict-free resolution for each key.
+ *   - `sync(other)` performs a full bidirectional merge with another node.
+ *
+ * @example
+ * ```typescript
+ * import { CrdtBackend } from 'network-ai';
+ *
+ * const nodeA = new CrdtBackend('node-a');
+ * const nodeB = new CrdtBackend('node-b');
+ *
+ * nodeA.write('status', 'idle',  'agent-1');
+ * nodeB.write('status', 'busy',  'agent-2');
+ *
+ * nodeA.sync(nodeB); // bidirectional merge
+ *
+ * // Both nodes now converge on the deterministic winner for 'status'
+ * console.log(nodeA.read('status')?.value === nodeB.read('status')?.value); // true
+ * ```
+ *
+ * @module BlackboardBackendCrdt
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrdtBackend = void 0;
+const crdt_1 = require("./crdt");
+// ============================================================================
+// CRDT BACKEND
+// ============================================================================
+/**
+ * CRDT-based `BlackboardBackend` for distributed multi-node agent coordination.
+ *
+ * Fully satisfies the synchronous `BlackboardBackend` interface while adding
+ * vector-clock-based merge semantics for deterministic convergence across nodes.
+ *
+ * All reads and writes are O(1). `merge()` is O(n) in the number of incoming
+ * entries. `sync()` is O(n + m) in the combined store sizes.
+ */
+class CrdtBackend {
+    _nodeId;
+    _clock = {};
+    _store = new Map();
+    /**
+     * Create a new `CrdtBackend` node.
+     *
+     * @param nodeId  Unique node identifier. Defaults to a random string.
+     * @param options Additional options.
+     */
+    constructor(nodeId, options) {
+        // nodeId param takes precedence; fall back to options.nodeId, then random
+        this._nodeId = nodeId ?? options?.nodeId ?? `node-${Math.random().toString(36).slice(2, 10)}`;
+    }
+    // --------------------------------------------------------------------------
+    // BlackboardBackend interface
+    // --------------------------------------------------------------------------
+    /**
+     * Read an entry. Returns `null` if not found, expired, or tombstoned.
+     */
+    read(key) {
+        const entry = this._store.get(key);
+        if (!entry)
+            return null;
+        if (entry.deleted)
+            return null;
+        if (this._isExpired(entry))
+            return null;
+        return entry;
+    }
+    /**
+     * Write a value to this node, incrementing the local vector clock.
+     * The entry is tagged with the current clock and this node's id.
+     */
+    write(key, value, sourceAgent, ttl) {
+        this._clock = (0, crdt_1.tickClock)(this._clock, this._nodeId);
+        const existing = this._store.get(key);
+        const version = (existing && !existing.deleted) ? existing.version + 1 : 1;
+        const entry = {
+            key,
+            value,
+            source_agent: sourceAgent,
+            timestamp: new Date().toISOString(),
+            ttl: ttl ?? null,
+            version,
+            vectorClock: { ...this._clock },
+            nodeId: this._nodeId,
+        };
+        this._store.set(key, entry);
+        return entry;
+    }
+    /**
+     * Delete an entry by recording a tombstone so the deletion propagates on
+     * sync to other nodes.
+     *
+     * Returns `true` if the key existed and was not already deleted.
+     */
+    delete(key) {
+        const existing = this._store.get(key);
+        if (!existing || existing.deleted)
+            return false;
+        this._clock = (0, crdt_1.tickClock)(this._clock, this._nodeId);
+        const tombstone = {
+            ...existing,
+            value: null,
+            deleted: true,
+            timestamp: new Date().toISOString(),
+            vectorClock: { ...this._clock },
+            nodeId: this._nodeId,
+        };
+        this._store.set(key, tombstone);
+        return true;
+    }
+    /**
+     * Return all non-expired, non-deleted keys.
+     */
+    listKeys() {
+        const keys = [];
+        for (const [key, entry] of this._store.entries()) {
+            if (!entry.deleted && !this._isExpired(entry)) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    /**
+     * Return a snapshot of all non-expired, non-deleted entries.
+     */
+    getSnapshot() {
+        const result = {};
+        for (const [key, entry] of this._store.entries()) {
+            if (!entry.deleted && !this._isExpired(entry)) {
+                result[key] = entry;
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // CRDT-specific API
+    // --------------------------------------------------------------------------
+    /**
+     * The unique node identifier for this backend instance.
+     */
+    get nodeId() {
+        return this._nodeId;
+    }
+    /**
+     * Return a copy of the current vector clock for this node.
+     */
+    getVectorClock() {
+        return { ...this._clock };
+    }
+    /**
+     * Return the raw `CrdtEntry` for a key, including tombstones and expired
+     * entries. Use `read()` for normal agent access.
+     *
+     * @returns The stored `CrdtEntry`, or `null` if the key has never been written.
+     */
+    getCrdtEntry(key) {
+        return this._store.get(key) ?? null;
+    }
+    /**
+     * Return a snapshot of all raw `CrdtEntry` records in this node's store,
+     * including tombstones and expired entries.
+     *
+     * Use this to obtain the payload for sending to another node's `merge()`.
+     */
+    getCrdtSnapshot() {
+        const result = {};
+        for (const [key, entry] of this._store.entries()) {
+            result[key] = entry;
+        }
+        return result;
+    }
+    /**
+     * Merge an array of `CrdtEntry` records from another node into this store.
+     *
+     * For each incoming entry:
+     *   - If this node has no entry for the key, store it directly.
+     *   - Otherwise, apply `mergeEntry()` to pick the winner deterministically.
+     *
+     * The local vector clock is advanced to the component-wise max of the
+     * current clock and all clocks carried in the incoming entries.
+     *
+     * @param entries  Entries from another node (obtained via `getCrdtSnapshot()`).
+     *
+     * @example
+     * ```typescript
+     * nodeA.merge(Object.values(nodeB.getCrdtSnapshot()));
+     * ```
+     */
+    merge(entries) {
+        for (const incoming of entries) {
+            // Advance our clock to acknowledge the remote writes
+            this._clock = (0, crdt_1.mergeClock)(this._clock, incoming.vectorClock);
+            const local = this._store.get(incoming.key);
+            if (!local) {
+                this._store.set(incoming.key, incoming);
+            }
+            else {
+                this._store.set(incoming.key, (0, crdt_1.mergeEntry)(local, incoming));
+            }
+        }
+    }
+    /**
+     * Bidirectionally synchronise this node with `other`.
+     *
+     * After `sync()`, both nodes will have merged each other's entire store and
+     * converge to the same state for every key.
+     *
+     * Equivalent to:
+     * ```typescript
+     * const mine   = Object.values(this.getCrdtSnapshot());
+     * const theirs = Object.values(other.getCrdtSnapshot());
+     * this.merge(theirs);
+     * other.merge(mine);
+     * ```
+     *
+     * @param other  The remote `CrdtBackend` node to sync with.
+     */
+    sync(other) {
+        const myEntries = Object.values(this.getCrdtSnapshot());
+        const theirEntries = Object.values(other.getCrdtSnapshot());
+        this.merge(theirEntries);
+        other.merge(myEntries);
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    _isExpired(entry) {
+        if (!entry.ttl)
+            return false;
+        return Date.now() > new Date(entry.timestamp).getTime() + entry.ttl * 1000;
+    }
+}
+exports.CrdtBackend = CrdtBackend;
+//# sourceMappingURL=blackboard-backend-crdt.js.map

package/dist/lib/blackboard-backend-crdt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackboard-backend-crdt.js","sourceRoot":"","sources":["../../lib/blackboard-backend-crdt.ts"],"names":[],"mappings":"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"}

package/dist/lib/consistency.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Configurable Consistency Levels for Blackboard Backends
+ *
+ * Wraps any `BlackboardBackend` with one of three consistency guarantees:
+ *
+ *  - `'eventual'`  (default) — writes return immediately; async replication
+ *                              happens in the background. Highest throughput.
+ *  - `'session'`             — read-your-writes guarantee. Every write made
+ *                              by this instance is immediately visible to
+ *                              subsequent reads, even before it propagates to
+ *                              other nodes. Tracked in a local session cache.
+ *  - `'strong'`              — writes are flushed to the backend before the
+ *                              async `writeAsync()` resolves. For backends
+ *                              that implement `FlushableBackend` (e.g.
+ *                              `RedisBackend`, `CrdtBackend`) this guarantees
+ *                              durability before the caller continues.
+ *
+ * Usage:
+ * ```typescript
+ * import { MemoryBackend } from './blackboard-backend';
+ * import { ConsistentBackend } from './consistency';
+ *
+ * const backend = new ConsistentBackend(new MemoryBackend(), 'session');
+ * backend.write('k', 'v', 'agent-1');
+ * backend.read('k'); // always returns 'v' in this session
+ * ```
+ *
+ * Integration with `getBlackboard()`:
+ * ```typescript
+ * const board = orchestrator.getBlackboard('live', {
+ *   backend: new RedisBackend(client),
+ *   consistency: 'strong',
+ * });
+ * ```
+ *
+ * @module Consistency
+ * @version 1.0.0
+ * @license MIT
+ */
+import type { BlackboardBackend, BlackboardEntry } from './blackboard-backend';
+/**
+ * The three supported consistency levels.
+ *
+ * | Level      | Read guarantee        | Write latency | Best for                        |
+ * |------------|-----------------------|---------------|---------------------------------|
+ * | `eventual` | Stale reads possible  | Lowest        | High-throughput, async pipelines|
+ * | `session`  | Read-your-writes      | Low           | Single-node agent sessions      |
+ * | `strong`   | Durable after `writeAsync` | Higher   | Critical state, audit trails    |
+ */
+export type ConsistencyLevel = 'eventual' | 'session' | 'strong';
+/**
+ * Optional extension of `BlackboardBackend` for backends that support an
+ * explicit flush operation (e.g. `RedisBackend`, `CrdtBackend`).
+ *
+ * `ConsistentBackend` automatically detects this interface at runtime and
+ * uses it for `'strong'` consistency writes via `writeAsync()`.
+ */
+export interface FlushableBackend extends BlackboardBackend {
+    /**
+     * Flush all pending writes to the durable store.
+     * Called by `ConsistentBackend` after each write under `'strong'` consistency.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Type guard — returns `true` if `backend` implements `FlushableBackend`.
+ *
+ * @example
+ * ```typescript
+ * if (isFlushable(backend)) {
+ *   await backend.flush();
+ * }
+ * ```
+ */
+export declare function isFlushable(backend: BlackboardBackend): backend is FlushableBackend;
+/**
+ * A `BlackboardBackend` wrapper that adds configurable consistency semantics.
+ *
+ * Fully satisfies the synchronous `BlackboardBackend` interface so it can be
+ * used anywhere a plain backend is accepted. For `'strong'` consistency, use
+ * `writeAsync()` to await durability confirmation.
+ *
+ * @example
+ * ```typescript
+ * // Session consistency — read-your-writes
+ * const backend = new ConsistentBackend(new MemoryBackend(), 'session');
+ * backend.write('task', 'pending', 'agent-1');
+ * backend.read('task'); // → 'pending' (guaranteed, even before replication)
+ *
+ * // Strong consistency with Redis
+ * const backend = new ConsistentBackend(new RedisBackend(client), 'strong');
+ * await backend.writeAsync('result', data, 'agent-1');
+ * // Redis has confirmed the write
+ * ```
+ */
+export declare class ConsistentBackend implements BlackboardBackend {
+    private readonly _backend;
+    private readonly _level;
+    /**
+     * Session write cache.
+     *
+     * - `BlackboardEntry`  → written in this session (overrides backend reads)
+     * - `null`             → deleted in this session (hides backend reads)
+     *
+     * Only populated for `'session'` consistency.
+     */
+    private readonly _session;
+    /**
+     * Create a new `ConsistentBackend`.
+     *
+     * @param backend  The underlying storage backend to wrap.
+     * @param level    Consistency level. Defaults to `'eventual'`.
+     */
+    constructor(backend: BlackboardBackend, level?: ConsistencyLevel);
+    /**
+     * Read an entry.
+     *
+     * - `eventual` / `strong`: delegates directly to the underlying backend.
+     * - `session`: returns the session-cached entry if present; falls back to
+     *   the backend. Returns `null` for session-deleted keys even if the backend
+     *   still has them.
+     */
+    read(key: string): BlackboardEntry | null;
+    /**
+     * Write a value synchronously.
+     *
+     * For all consistency levels this writes immediately to the underlying
+     * backend. For `'session'` the result is also cached locally so subsequent
+     * `read()` calls see it without waiting for replication.
+     *
+     * For `'strong'` consistency, prefer `writeAsync()` to await durability.
+     */
+    write(key: string, value: unknown, sourceAgent: string, ttl?: number): BlackboardEntry;
+    /**
+     * Delete an entry.
+     *
+     * For `'session'` consistency, also records a session-tombstone so the key
+     * appears deleted to subsequent `read()` calls in this session.
+     */
+    delete(key: string): boolean;
+    /**
+     * Return all non-expired, non-deleted keys.
+     *
+     * For `'session'` consistency, session-written keys are included even if
+     * not yet visible in the backend; session-deleted keys are excluded.
+     */
+    listKeys(): string[];
+    /**
+     * Return a snapshot of all non-expired, non-deleted entries.
+     *
+     * For `'session'` consistency, session writes overlay the backend snapshot.
+     */
+    getSnapshot(): Record<string, BlackboardEntry>;
+    /**
+     * Write a value and, for `'strong'` consistency, await durability
+     * confirmation from the backend.
+     *
+     * - `eventual` / `session`: behaves identically to `write()` but returns
+     *   a `Promise` for API uniformity.
+     * - `strong` + `FlushableBackend`: calls `backend.flush()` after the write
+     *   and resolves only after the flush completes.
+     * - `strong` + non-flushable backend: writes synchronously and resolves
+     *   immediately (backend writes are already synchronous/durable).
+     *
+     * @example
+     * ```typescript
+     * const entry = await backend.writeAsync('checkpoint', data, 'agent-1');
+     * // Under 'strong' + RedisBackend: Redis has persisted the entry by here
+     * ```
+     */
+    writeAsync(key: string, value: unknown, sourceAgent: string, ttl?: number): Promise<BlackboardEntry>;
+    /**
+     * The configured consistency level.
+     */
+    get consistencyLevel(): ConsistencyLevel;
+    /**
+     * The underlying backend being wrapped.
+     */
+    get backend(): BlackboardBackend;
+    /**
+     * Number of entries currently in the session cache (live + tombstones).
+     * Always `0` for `'eventual'` and `'strong'` levels.
+     */
+    get sessionSize(): number;
+    /**
+     * Clear the session write cache without modifying the underlying backend.
+     *
+     * After calling this, `read()` will reflect the backend state directly.
+     * Only meaningful for `'session'` consistency.
+     */
+    clearSession(): void;
+    private _isExpired;
+}
+//# sourceMappingURL=consistency.d.ts.map

package/dist/lib/consistency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consistency.d.ts","sourceRoot":"","sources":["../../lib/consistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAM/E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAMjE;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,IAAI,gBAAgB,CAEnF;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;IAE3E;;;;;OAKG;gBACS,OAAO,EAAE,iBAAiB,EAAE,KAAK,GAAE,gBAA6B;IAS5E;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAoBzC;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe;IAQtF;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQ5B;;;;;OAKG;IACH,QAAQ,IAAI,MAAM,EAAE;IAqBpB;;;;OAIG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAwB9C;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC;IAQ3B;;OAEG;IACH,IAAI,gBAAgB,IAAI,gBAAgB,CAEvC;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,iBAAiB,CAE/B;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;OAKG;IACH,YAAY,IAAI,IAAI;IAQpB,OAAO,CAAC,UAAU;CAInB"}