network-ai 3.7.0 → 3.8.0

package/dist/lib/consistency.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsistentBackend = void 0;
+exports.isFlushable = isFlushable;
+/**
+ * Type guard — returns `true` if `backend` implements `FlushableBackend`.
+ *
+ * @example
+ * ```typescript
+ * if (isFlushable(backend)) {
+ *   await backend.flush();
+ * }
+ * ```
+ */
+function isFlushable(backend) {
+    return typeof backend.flush === 'function';
+}
+// ============================================================================
+// CONSISTENT BACKEND
+// ============================================================================
+/**
+ * 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
+ * ```
+ */
+class ConsistentBackend {
+    _backend;
+    _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.
+     */
+    _session = new Map();
+    /**
+     * Create a new `ConsistentBackend`.
+     *
+     * @param backend  The underlying storage backend to wrap.
+     * @param level    Consistency level. Defaults to `'eventual'`.
+     */
+    constructor(backend, level = 'eventual') {
+        this._backend = backend;
+        this._level = level;
+    }
+    // --------------------------------------------------------------------------
+    // BlackboardBackend interface
+    // --------------------------------------------------------------------------
+    /**
+     * 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) {
+        if (this._level === 'session') {
+            const cached = this._session.get(key);
+            if (cached === undefined) {
+                // Not in session cache — fall through to backend
+            }
+            else if (cached === null) {
+                // Session-deleted tombstone
+                return null;
+            }
+            else {
+                // Live session entry — check expiry
+                if (this._isExpired(cached)) {
+                    this._session.delete(key);
+                    return null;
+                }
+                return cached;
+            }
+        }
+        return this._backend.read(key);
+    }
+    /**
+     * 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, value, sourceAgent, ttl) {
+        const entry = this._backend.write(key, value, sourceAgent, ttl);
+        if (this._level === 'session') {
+            this._session.set(key, entry);
+        }
+        return entry;
+    }
+    /**
+     * 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) {
+        const result = this._backend.delete(key);
+        if (this._level === 'session') {
+            this._session.set(key, null); // tombstone
+        }
+        return result;
+    }
+    /**
+     * 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() {
+        if (this._level !== 'session') {
+            return this._backend.listKeys();
+        }
+        // Start with backend keys, then overlay session mutations
+        const backendKeys = new Set(this._backend.listKeys());
+        // Add session-written keys (not yet in backend, or overriding backend)
+        for (const [key, entry] of this._session.entries()) {
+            if (entry === null) {
+                // Session delete — remove from result
+                backendKeys.delete(key);
+            }
+            else if (!this._isExpired(entry)) {
+                backendKeys.add(key);
+            }
+        }
+        return Array.from(backendKeys);
+    }
+    /**
+     * Return a snapshot of all non-expired, non-deleted entries.
+     *
+     * For `'session'` consistency, session writes overlay the backend snapshot.
+     */
+    getSnapshot() {
+        if (this._level !== 'session') {
+            return this._backend.getSnapshot();
+        }
+        // Start from backend snapshot, apply session overlay
+        const result = { ...this._backend.getSnapshot() };
+        for (const [key, entry] of this._session.entries()) {
+            if (entry === null) {
+                // Session delete
+                delete result[key];
+            }
+            else if (!this._isExpired(entry)) {
+                result[key] = entry;
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // Extended consistency API
+    // --------------------------------------------------------------------------
+    /**
+     * 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
+     * ```
+     */
+    async writeAsync(key, value, sourceAgent, ttl) {
+        const entry = this.write(key, value, sourceAgent, ttl);
+        if (this._level === 'strong' && isFlushable(this._backend)) {
+            await this._backend.flush();
+        }
+        return entry;
+    }
+    /**
+     * The configured consistency level.
+     */
+    get consistencyLevel() {
+        return this._level;
+    }
+    /**
+     * The underlying backend being wrapped.
+     */
+    get backend() {
+        return this._backend;
+    }
+    /**
+     * Number of entries currently in the session cache (live + tombstones).
+     * Always `0` for `'eventual'` and `'strong'` levels.
+     */
+    get sessionSize() {
+        return this._session.size;
+    }
+    /**
+     * 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() {
+        this._session.clear();
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    _isExpired(entry) {
+        if (!entry.ttl)
+            return false;
+        return Date.now() > new Date(entry.timestamp).getTime() + entry.ttl * 1000;
+    }
+}
+exports.ConsistentBackend = ConsistentBackend;
+//# sourceMappingURL=consistency.js.map

package/dist/lib/consistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consistency.js","sourceRoot":"","sources":["../../lib/consistency.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAgDH,kCAEC;AAZD;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,OAA0B;IACpD,OAAO,OAAQ,OAA4B,CAAC,KAAK,KAAK,UAAU,CAAC;AACnE,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,iBAAiB;IACX,QAAQ,CAAoB;IAC5B,MAAM,CAAmB;IAE1C;;;;;;;OAOG;IACc,QAAQ,GAAwC,IAAI,GAAG,EAAE,CAAC;IAE3E;;;;;OAKG;IACH,YAAY,OAA0B,EAAE,QAA0B,UAAU;QAC1E,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,6EAA6E;IAC7E,8BAA8B;IAC9B,6EAA6E;IAE7E;;;;;;;OAOG;IACH,IAAI,CAAC,GAAW;QACd,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,iDAAiD;YACnD,CAAC;iBAAM,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC3B,4BAA4B;gBAC5B,OAAO,IAAI,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,oCAAoC;gBACpC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC1B,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAW,EAAE,KAAc,EAAE,WAAmB,EAAE,GAAY;QAClE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QAChE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAW;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY;QAC5C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACN,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAClC,CAAC;QAED,0DAA0D;QAC1D,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEtD,uEAAuE;QACvE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACnD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,sCAAsC;gBACtC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;iBAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACrC,CAAC;QAED,qDAAqD;QACrD,MAAM,MAAM,GAAoC,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAEnF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACnD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,iBAAiB;gBACjB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;iBAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6EAA6E;IAC7E,2BAA2B;IAC3B,6EAA6E;IAE7E;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,UAAU,CACd,GAAW,EACX,KAAc,EACd,WAAmB,EACnB,GAAY;QAEZ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,YAAY;QACV,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,6EAA6E;IAC7E,kBAAkB;IAClB,6EAA6E;IAErE,UAAU,CAAC,KAAsB;QACvC,IAAI,CAAC,KAAK,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC;IAC7E,CAAC;CACF;AAtND,8CAsNC"}

package/dist/lib/federated-budget.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Federated Budget Tracking
+ *
+ * Tracks token spending across distributed agent swarms. Each `FederatedBudget`
+ * instance enforces a global ceiling shared among all agents that call `spend()`.
+ *
+ * When an optional `BlackboardBackend` is supplied, the budget state is written
+ * to the blackboard after every mutation. Wiring a `CrdtBackend` or `RedisBackend`
+ * as the underlying backend therefore gives automatic cross-node synchronization
+ * with no extra configuration.
+ *
+ * Architecture:
+ *   - In-memory `spent` map keyed by `agentId` holds per-agent cumulative totals.
+ *   - `spend()` is synchronous and enforces both the global ceiling and an optional
+ *     per-agent ceiling in a single check.
+ *   - A `blackboard` backend (if supplied) stores a JSON snapshot under `budgetKey`
+ *     after every `spend()` / `reset()` / `setCeiling()` call so distributed nodes
+ *     can read the latest state.
+ *   - `loadFromBlackboard()` deserializes a previously saved snapshot so a
+ *     restarted node can recover its prior accumulated spend.
+ *
+ * @example
+ * ```typescript
+ * import { FederatedBudget } from 'network-ai';
+ *
+ * const budget = new FederatedBudget({ ceiling: 10_000 });
+ *
+ * budget.spend('agent-1', 3000); // { allowed: true,  remaining: 7000 }
+ * budget.spend('agent-2', 8000); // { allowed: false, remaining: 7000 }
+ * budget.remaining();            // 7000
+ * budget.getSpendLog();          // { 'agent-1': 3000 }
+ * ```
+ *
+ * @example With blackboard persistence
+ * ```typescript
+ * import { CrdtBackend } from 'network-ai';
+ * import { FederatedBudget } from 'network-ai';
+ *
+ * const node = new CrdtBackend('node-a');
+ * const budget = new FederatedBudget({ ceiling: 50_000, blackboard: node });
+ *
+ * budget.spend('agent-1', 1000);
+ * // State is now stored in node under 'federated-budget'
+ * // Sync node to other CrdtBackend nodes to propagate the spend.
+ * ```
+ *
+ * @module FederatedBudget
+ * @version 1.0.0
+ * @license MIT
+ */
+import type { BlackboardBackend } from './blackboard-backend';
+/**
+ * Result returned by {@link FederatedBudget.spend}.
+ */
+export interface SpendResult {
+    /** Whether the spend was allowed (i.e. did not breach any ceiling). */
+    allowed: boolean;
+    /** Remaining tokens in the global pool after this call. */
+    remaining: number;
+    /** Reason the spend was denied, if `allowed` is `false`. */
+    deniedReason?: 'global_ceiling' | 'per_agent_ceiling';
+}
+/**
+ * A single entry in the spend log returned by {@link FederatedBudget.getSpendLog}.
+ */
+export interface SpendLogEntry {
+    /** Agent that made the spend. */
+    agentId: string;
+    /** Number of tokens spent in this transaction. */
+    tokens: number;
+    /** ISO timestamp of the spend. */
+    timestamp: string;
+}
+/**
+ * Construction options for {@link FederatedBudget}.
+ */
+export interface FederatedBudgetOptions {
+    /**
+     * Global token ceiling shared across all agents.
+     * No single call to `spend()` may push the cumulative total above this value.
+     * Must be a positive integer.
+     */
+    ceiling: number;
+    /**
+     * Optional per-agent ceiling.
+     * When set, each individual agent is also capped at this many cumulative tokens,
+     * independently of the global ceiling.
+     * Must be a positive integer if provided.
+     */
+    perAgentCeiling?: number;
+    /**
+     * Optional blackboard backend.
+     * When provided, budget state is persisted under `budgetKey` after every
+     * mutation so distributed nodes can observe the latest spend.
+     *
+     * Pair with a `CrdtBackend` or `RedisBackend` for automatic multi-node sync.
+     */
+    blackboard?: BlackboardBackend;
+    /**
+     * Key used to store the budget snapshot on the blackboard.
+     * Defaults to `'federated-budget'`.
+     */
+    budgetKey?: string;
+    /**
+     * Agent identifier used as the `agentId` when writing to the blackboard.
+     * Defaults to `'federated-budget-tracker'`.
+     */
+    blackboardAgent?: string;
+}
+/**
+ * Federated token-budget tracker for distributed agent swarms.
+ *
+ * Enforces a shared global ceiling across all agents and optionally an
+ * individual per-agent ceiling. State can be persisted to any
+ * `BlackboardBackend` for cross-node visibility.
+ */
+export declare class FederatedBudget {
+    private readonly _ceiling;
+    private _dynamicCeiling;
+    private readonly _perAgentCeiling;
+    private readonly _spent;
+    private _totalSpent;
+    private readonly _log;
+    private readonly _blackboard;
+    private readonly _budgetKey;
+    private readonly _bbAgent;
+    constructor(options: FederatedBudgetOptions);
+    /**
+     * Attempt to spend `tokens` on behalf of `agentId`.
+     *
+     * The spend is allowed only when:
+     *   1. `totalSpent + tokens <= ceiling` (global ceiling not breached), AND
+     *   2. `agentSpent + tokens <= perAgentCeiling` if a per-agent ceiling is set.
+     *
+     * When allowed the internal counters are updated and the state is persisted
+     * to the blackboard (if configured).
+     *
+     * @param agentId  Identifier of the spending agent. Must be a non-empty string.
+     * @param tokens   Number of tokens to spend. Must be a positive integer.
+     * @returns        `SpendResult` with `allowed`, `remaining`, and optional `deniedReason`.
+     */
+    spend(agentId: string, tokens: number): SpendResult;
+    /**
+     * Remaining tokens in the global pool.
+     */
+    remaining(): number;
+    /**
+     * Total tokens spent across all agents.
+     */
+    getTotalSpent(): number;
+    /**
+     * Tokens spent by a specific agent. Returns `0` if the agent has no spend.
+     */
+    getAgentSpent(agentId: string): number;
+    /**
+     * Per-agent spend totals as a plain object: `{ agentId: totalTokens }`.
+     */
+    getSpendLog(): Record<string, number>;
+    /**
+     * Detailed transaction log — every individual `spend()` call in order.
+     */
+    getTransactionLog(): SpendLogEntry[];
+    /**
+     * Current global ceiling (may differ from the original if `setCeiling()` was called).
+     */
+    getCeiling(): number;
+    /**
+     * Per-agent ceiling, or `undefined` if none was configured.
+     */
+    getPerAgentCeiling(): number | undefined;
+    /**
+     * Dynamically adjust the global ceiling.
+     *
+     * The new ceiling must be a positive finite number. It may be set below
+     * the current `totalSpent` (no previously approved spends are reversed, but
+     * future spends will be denied until tokens are freed by a `reset()`).
+     *
+     * @param ceiling  New global ceiling.
+     */
+    setCeiling(ceiling: number): void;
+    /**
+     * Reset all spend counters and clear the transaction log.
+     *
+     * The global ceiling is preserved (its current value after any `setCeiling()`
+     * calls). After a reset `remaining() === getCeiling()`.
+     *
+     * The blackboard entry (if configured) is updated with the reset state.
+     */
+    reset(): void;
+    /**
+     * Restore budget state from the blackboard backend.
+     *
+     * Reads the entry stored under `budgetKey`, deserializes the snapshot, and
+     * replaces the current in-memory state. Useful when a node restarts and
+     * needs to recover its prior accumulated spend.
+     *
+     * No-op (returns `false`) when no blackboard is configured or no entry exists.
+     *
+     * @returns `true` if state was successfully loaded, `false` otherwise.
+     */
+    loadFromBlackboard(): boolean;
+    /** Serialize current state to the blackboard, if one is configured. */
+    private _persist;
+}
+//# sourceMappingURL=federated-budget.d.ts.map

package/dist/lib/federated-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federated-budget.d.ts","sourceRoot":"","sources":["../../lib/federated-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAiBD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAE/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,EAAE,sBAAsB;IAyB3C;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;IA6CnD;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAItC;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQrC;;OAEG;IACH,iBAAiB,IAAI,aAAa,EAAE;IAIpC;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,kBAAkB,IAAI,MAAM,GAAG,SAAS;IAIxC;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQjC;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;;;;;;OAUG;IACH,kBAAkB,IAAI,OAAO;IAsB7B,uEAAuE;IACvE,OAAO,CAAC,QAAQ;CAcjB"}