claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/guidance/dist/memory-gate.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Memory Write Gating System
+ *
+ * Adds authority scope, TTL, decay, and contradiction tracking
+ * to memory operations. Ensures that only authorized agents can
+ * write to specific namespaces, enforces rate limits, and detects
+ * contradictions between memory entries.
+ *
+ * @module @claude-flow/guidance/memory-gate
+ */
+/**
+ * Authority definition for a memory-writing agent
+ */
+export interface MemoryAuthority {
+    /** Agent identifier */
+    agentId: string;
+    /** Role in the hierarchy */
+    role: 'queen' | 'coordinator' | 'worker' | 'observer';
+    /** Namespaces this agent is allowed to write to */
+    namespaces: string[];
+    /** Maximum writes allowed per minute */
+    maxWritesPerMinute: number;
+    /** Whether this agent can delete entries */
+    canDelete: boolean;
+    /** Whether this agent can overwrite existing entries */
+    canOverwrite: boolean;
+    /** Trust level from 0 (untrusted) to 1 (fully trusted) */
+    trustLevel: number;
+}
+/**
+ * A gated memory entry with metadata for TTL, decay, lineage, and contradictions
+ */
+export interface MemoryEntry {
+    /** Entry key */
+    key: string;
+    /** Namespace the entry belongs to */
+    namespace: string;
+    /** The stored value */
+    value: unknown;
+    /** SHA-256 hash of the serialized value */
+    valueHash: string;
+    /** Authority that created/last wrote this entry */
+    authority: MemoryAuthority;
+    /** Timestamp when the entry was created (ms since epoch) */
+    createdAt: number;
+    /** Timestamp of the last update (ms since epoch) */
+    updatedAt: number;
+    /** Time-to-live in milliseconds, or null for no expiry */
+    ttlMs: number | null;
+    /** Decay rate from 0 (no decay) to 1 (immediate decay) */
+    decayRate: number;
+    /** Confidence score from 0 to 1, decays over time */
+    confidence: number;
+    /** Lineage tracking for provenance */
+    lineage: {
+        parentKey?: string;
+        derivedFrom?: string[];
+        operation: string;
+    };
+    /** Detected contradictions with other entries */
+    contradictions: Array<{
+        entryKey: string;
+        description: string;
+        resolvedAt?: number;
+    }>;
+}
+/**
+ * Result of evaluating a write request
+ */
+export interface WriteDecision {
+    /** Whether the write is allowed */
+    allowed: boolean;
+    /** Human-readable reason for the decision */
+    reason: string;
+    /** Contradictions detected with existing entries */
+    contradictions: Array<{
+        existingKey: string;
+        description: string;
+    }>;
+    /** Authority check result */
+    authorityCheck: {
+        passed: boolean;
+        requiredRole: string;
+        actualRole: string;
+    };
+    /** Rate limit check result */
+    rateCheck: {
+        passed: boolean;
+        writesInWindow: number;
+        limit: number;
+    };
+    /** Overwrite permission check result */
+    overwriteCheck: {
+        isOverwrite: boolean;
+        allowed: boolean;
+    };
+}
+/**
+ * Configuration for the MemoryWriteGate
+ */
+export interface MemoryWriteGateConfig {
+    /** Pre-registered authorities */
+    authorities?: MemoryAuthority[];
+    /** Similarity threshold for contradiction detection (0-1) */
+    contradictionThreshold?: number;
+    /** Default TTL for new entries in ms (null = no expiry) */
+    defaultTtlMs?: number;
+    /** Default decay rate for new entries (0-1) */
+    defaultDecayRate?: number;
+    /** Whether to run contradiction detection on writes */
+    enableContradictionTracking?: boolean;
+}
+/**
+ * Memory Write Gate
+ *
+ * Controls write access to the memory system by enforcing:
+ * - Authority checks (namespace access, role hierarchy)
+ * - Rate limiting (sliding window per agent)
+ * - Overwrite permissions
+ * - Contradiction detection against existing entries
+ * - TTL and confidence decay tracking
+ */
+export declare class MemoryWriteGate {
+    private authorities;
+    private writeTimestamps;
+    private contradictionThreshold;
+    private defaultTtlMs;
+    private defaultDecayRate;
+    private enableContradictionTracking;
+    private contradictionResolutions;
+    constructor(config?: MemoryWriteGateConfig);
+    /**
+     * Evaluate whether a write operation should be allowed.
+     *
+     * Steps:
+     * 1. Check authority (namespace allowed, role sufficient)
+     * 2. Check rate limit
+     * 3. Check overwrite permission
+     * 4. Detect contradictions against existing entries
+     * 5. Return decision
+     */
+    evaluateWrite(authority: MemoryAuthority, key: string, namespace: string, value: unknown, existingEntries?: MemoryEntry[]): WriteDecision;
+    /**
+     * Register a new authority or update an existing one
+     */
+    registerAuthority(authority: MemoryAuthority): void;
+    /**
+     * Compute the current confidence for an entry based on decay over time.
+     *
+     * Uses exponential decay: confidence = initialConfidence * e^(-decayRate * ageHours)
+     * where ageHours is (now - updatedAt) / 3600000
+     */
+    computeConfidence(entry: MemoryEntry): number;
+    /**
+     * Get all entries whose TTL has been exceeded
+     */
+    getExpiredEntries(entries: MemoryEntry[]): MemoryEntry[];
+    /**
+     * Get entries whose decayed confidence has dropped below a threshold
+     */
+    getDecayedEntries(entries: MemoryEntry[], threshold: number): MemoryEntry[];
+    /**
+     * Detect contradictions between a new value and existing entries.
+     *
+     * Uses string-based pattern matching to find conflicting statements
+     * (must vs never, always vs never, require vs forbid, etc.)
+     */
+    detectContradictions(newValue: unknown, existingEntries: MemoryEntry[]): Array<{
+        entryKey: string;
+        description: string;
+    }>;
+    /**
+     * Mark a contradiction as resolved
+     */
+    resolveContradiction(entryKey: string, resolution: string): void;
+    /**
+     * Get the authority for an agent by ID
+     */
+    getAuthorityFor(agentId: string): MemoryAuthority | undefined;
+    /**
+     * Get the current rate limit status for an agent
+     */
+    getRateLimitStatus(agentId: string): {
+        writesInWindow: number;
+        limit: number;
+        resetAt: number;
+    };
+    /** Get the default TTL in ms */
+    getDefaultTtlMs(): number | null;
+    /** Get the default decay rate */
+    getDefaultDecayRate(): number;
+    /** Check if contradiction tracking is enabled */
+    isContradictionTrackingEnabled(): boolean;
+    /** Get the contradiction resolution for an entry key */
+    getContradictionResolution(entryKey: string): string | undefined;
+    /**
+     * Check whether an authority is allowed to write to a namespace
+     */
+    private checkAuthority;
+    /**
+     * Check rate limit using a sliding window of write timestamps
+     */
+    private checkRateLimit;
+    /**
+     * Record a write timestamp for an agent
+     */
+    private recordWrite;
+}
+/**
+ * Create a MemoryWriteGate instance with optional configuration
+ */
+export declare function createMemoryWriteGate(config?: MemoryWriteGateConfig): MemoryWriteGate;
+/**
+ * Create a new MemoryEntry with defaults applied
+ */
+export declare function createMemoryEntry(key: string, namespace: string, value: unknown, authority: MemoryAuthority, options?: {
+    ttlMs?: number | null;
+    decayRate?: number;
+    confidence?: number;
+    lineage?: MemoryEntry['lineage'];
+}): MemoryEntry;
+//# sourceMappingURL=memory-gate.d.ts.map

package/v3/@claude-flow/guidance/dist/memory-gate.js

@@ -0,0 +1,382 @@
+/**
+ * Memory Write Gating System
+ *
+ * Adds authority scope, TTL, decay, and contradiction tracking
+ * to memory operations. Ensures that only authorized agents can
+ * write to specific namespaces, enforces rate limits, and detects
+ * contradictions between memory entries.
+ *
+ * @module @claude-flow/guidance/memory-gate
+ */
+import { createHash } from 'node:crypto';
+// ============================================================================
+// Role Hierarchy
+// ============================================================================
+/** Role hierarchy levels (higher = more authority) */
+const ROLE_HIERARCHY = {
+    queen: 4,
+    coordinator: 3,
+    worker: 2,
+    observer: 1,
+};
+/**
+ * Minimum role required to write to any namespace
+ */
+const MINIMUM_WRITE_ROLE = 'worker';
+// ============================================================================
+// Contradiction Detection Patterns
+// ============================================================================
+const CONTRADICTION_PATTERNS = [
+    {
+        positive: /\bmust\b/i,
+        negative: /\bnever\b|\bdo not\b|\bavoid\b/i,
+        description: 'Conflicting obligation: "must" vs negation',
+    },
+    {
+        positive: /\balways\b/i,
+        negative: /\bnever\b|\bdon't\b|\bdo not\b/i,
+        description: 'Conflicting frequency: "always" vs "never"',
+    },
+    {
+        positive: /\brequire\b/i,
+        negative: /\bforbid\b|\bprohibit\b/i,
+        description: 'Conflicting policy: "require" vs "forbid"',
+    },
+    {
+        positive: /\benable\b/i,
+        negative: /\bdisable\b/i,
+        description: 'Conflicting state: "enable" vs "disable"',
+    },
+    {
+        positive: /\btrue\b/i,
+        negative: /\bfalse\b/i,
+        description: 'Conflicting boolean: "true" vs "false"',
+    },
+];
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Compute SHA-256 hash of a value
+ */
+function computeValueHash(value) {
+    const serialized = JSON.stringify(value);
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Stringify a value for contradiction detection
+ */
+function stringifyForComparison(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+// ============================================================================
+// MemoryWriteGate
+// ============================================================================
+/**
+ * Memory Write Gate
+ *
+ * Controls write access to the memory system by enforcing:
+ * - Authority checks (namespace access, role hierarchy)
+ * - Rate limiting (sliding window per agent)
+ * - Overwrite permissions
+ * - Contradiction detection against existing entries
+ * - TTL and confidence decay tracking
+ */
+export class MemoryWriteGate {
+    authorities = new Map();
+    writeTimestamps = new Map();
+    contradictionThreshold;
+    defaultTtlMs;
+    defaultDecayRate;
+    enableContradictionTracking;
+    contradictionResolutions = new Map();
+    constructor(config = {}) {
+        this.contradictionThreshold = config.contradictionThreshold ?? 0.5;
+        this.defaultTtlMs = config.defaultTtlMs ?? null;
+        this.defaultDecayRate = config.defaultDecayRate ?? 0;
+        this.enableContradictionTracking = config.enableContradictionTracking ?? true;
+        if (config.authorities) {
+            for (const authority of config.authorities) {
+                this.authorities.set(authority.agentId, authority);
+            }
+        }
+    }
+    /**
+     * Evaluate whether a write operation should be allowed.
+     *
+     * Steps:
+     * 1. Check authority (namespace allowed, role sufficient)
+     * 2. Check rate limit
+     * 3. Check overwrite permission
+     * 4. Detect contradictions against existing entries
+     * 5. Return decision
+     */
+    evaluateWrite(authority, key, namespace, value, existingEntries) {
+        const reasons = [];
+        let allowed = true;
+        // Step 1: Authority check
+        const authorityCheck = this.checkAuthority(authority, namespace);
+        if (!authorityCheck.passed) {
+            allowed = false;
+            reasons.push(`Authority check failed: role "${authority.role}" insufficient or namespace "${namespace}" not allowed`);
+        }
+        // Step 2: Rate limit check
+        const rateCheck = this.checkRateLimit(authority);
+        if (!rateCheck.passed) {
+            allowed = false;
+            reasons.push(`Rate limit exceeded: ${rateCheck.writesInWindow}/${rateCheck.limit} writes in window`);
+        }
+        // Step 3: Overwrite check
+        const isOverwrite = existingEntries
+            ? existingEntries.some((e) => e.key === key && e.namespace === namespace)
+            : false;
+        const overwriteCheck = {
+            isOverwrite,
+            allowed: isOverwrite ? authority.canOverwrite : true,
+        };
+        if (isOverwrite && !authority.canOverwrite) {
+            allowed = false;
+            reasons.push('Overwrite not permitted for this authority');
+        }
+        // Step 4: Contradiction detection
+        let contradictions = [];
+        if (this.enableContradictionTracking &&
+            existingEntries &&
+            existingEntries.length > 0) {
+            const raw = this.detectContradictions(value, existingEntries);
+            contradictions = raw.map((c) => ({
+                existingKey: c.entryKey,
+                description: c.description,
+            }));
+        }
+        // Step 5: Record write timestamp if allowed
+        if (allowed) {
+            this.recordWrite(authority.agentId);
+        }
+        const reason = allowed
+            ? 'Write allowed'
+            : reasons.join('; ');
+        return {
+            allowed,
+            reason,
+            contradictions,
+            authorityCheck,
+            rateCheck,
+            overwriteCheck,
+        };
+    }
+    /**
+     * Register a new authority or update an existing one
+     */
+    registerAuthority(authority) {
+        this.authorities.set(authority.agentId, authority);
+    }
+    /**
+     * Compute the current confidence for an entry based on decay over time.
+     *
+     * Uses exponential decay: confidence = initialConfidence * e^(-decayRate * ageHours)
+     * where ageHours is (now - updatedAt) / 3600000
+     */
+    computeConfidence(entry) {
+        if (entry.decayRate === 0)
+            return entry.confidence;
+        if (entry.decayRate >= 1)
+            return 0;
+        const now = Date.now();
+        const ageMs = now - entry.updatedAt;
+        const ageHours = ageMs / 3_600_000;
+        const decayed = entry.confidence * Math.exp(-entry.decayRate * ageHours);
+        return Math.max(0, Math.min(1, decayed));
+    }
+    /**
+     * Get all entries whose TTL has been exceeded
+     */
+    getExpiredEntries(entries) {
+        const now = Date.now();
+        return entries.filter((entry) => {
+            if (entry.ttlMs === null)
+                return false;
+            return now - entry.createdAt > entry.ttlMs;
+        });
+    }
+    /**
+     * Get entries whose decayed confidence has dropped below a threshold
+     */
+    getDecayedEntries(entries, threshold) {
+        return entries.filter((entry) => {
+            const currentConfidence = this.computeConfidence(entry);
+            return currentConfidence < threshold;
+        });
+    }
+    /**
+     * Detect contradictions between a new value and existing entries.
+     *
+     * Uses string-based pattern matching to find conflicting statements
+     * (must vs never, always vs never, require vs forbid, etc.)
+     */
+    detectContradictions(newValue, existingEntries) {
+        const newText = stringifyForComparison(newValue);
+        const contradictions = [];
+        for (const entry of existingEntries) {
+            const existingText = stringifyForComparison(entry.value);
+            for (const pattern of CONTRADICTION_PATTERNS) {
+                const newMatchesPositive = pattern.positive.test(newText) && pattern.negative.test(existingText);
+                const newMatchesNegative = pattern.negative.test(newText) && pattern.positive.test(existingText);
+                if (newMatchesPositive || newMatchesNegative) {
+                    contradictions.push({
+                        entryKey: entry.key,
+                        description: pattern.description,
+                    });
+                    break; // Only report the first contradiction per entry
+                }
+            }
+        }
+        return contradictions;
+    }
+    /**
+     * Mark a contradiction as resolved
+     */
+    resolveContradiction(entryKey, resolution) {
+        this.contradictionResolutions.set(entryKey, resolution);
+    }
+    /**
+     * Get the authority for an agent by ID
+     */
+    getAuthorityFor(agentId) {
+        return this.authorities.get(agentId);
+    }
+    /**
+     * Get the current rate limit status for an agent
+     */
+    getRateLimitStatus(agentId) {
+        const authority = this.authorities.get(agentId);
+        const limit = authority?.maxWritesPerMinute ?? 0;
+        const now = Date.now();
+        const windowMs = 60_000;
+        const windowStart = now - windowMs;
+        const timestamps = this.writeTimestamps.get(agentId) ?? [];
+        const recentWrites = timestamps.filter((t) => t > windowStart);
+        // Find the earliest write in the window to compute reset time
+        const resetAt = recentWrites.length > 0
+            ? recentWrites[0] + windowMs
+            : now;
+        return {
+            writesInWindow: recentWrites.length,
+            limit,
+            resetAt,
+        };
+    }
+    // ===== Accessors =====
+    /** Get the default TTL in ms */
+    getDefaultTtlMs() {
+        return this.defaultTtlMs;
+    }
+    /** Get the default decay rate */
+    getDefaultDecayRate() {
+        return this.defaultDecayRate;
+    }
+    /** Check if contradiction tracking is enabled */
+    isContradictionTrackingEnabled() {
+        return this.enableContradictionTracking;
+    }
+    /** Get the contradiction resolution for an entry key */
+    getContradictionResolution(entryKey) {
+        return this.contradictionResolutions.get(entryKey);
+    }
+    // ===== Private Methods =====
+    /**
+     * Check whether an authority is allowed to write to a namespace
+     */
+    checkAuthority(authority, namespace) {
+        const roleLevel = ROLE_HIERARCHY[authority.role];
+        const minimumLevel = ROLE_HIERARCHY[MINIMUM_WRITE_ROLE];
+        // Role check: must be at least 'worker' level
+        if (roleLevel < minimumLevel) {
+            return {
+                passed: false,
+                requiredRole: MINIMUM_WRITE_ROLE,
+                actualRole: authority.role,
+            };
+        }
+        // Namespace check: must be in allowed list, or queen can write anywhere
+        if (authority.role !== 'queen' && !authority.namespaces.includes(namespace)) {
+            return {
+                passed: false,
+                requiredRole: MINIMUM_WRITE_ROLE,
+                actualRole: authority.role,
+            };
+        }
+        return {
+            passed: true,
+            requiredRole: MINIMUM_WRITE_ROLE,
+            actualRole: authority.role,
+        };
+    }
+    /**
+     * Check rate limit using a sliding window of write timestamps
+     */
+    checkRateLimit(authority) {
+        const now = Date.now();
+        const windowMs = 60_000;
+        const windowStart = now - windowMs;
+        const timestamps = this.writeTimestamps.get(authority.agentId) ?? [];
+        // Prune old timestamps outside the window
+        const recentWrites = timestamps.filter((t) => t > windowStart);
+        this.writeTimestamps.set(authority.agentId, recentWrites);
+        return {
+            passed: recentWrites.length < authority.maxWritesPerMinute,
+            writesInWindow: recentWrites.length,
+            limit: authority.maxWritesPerMinute,
+        };
+    }
+    /**
+     * Record a write timestamp for an agent
+     */
+    recordWrite(agentId) {
+        const timestamps = this.writeTimestamps.get(agentId) ?? [];
+        timestamps.push(Date.now());
+        this.writeTimestamps.set(agentId, timestamps);
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a MemoryWriteGate instance with optional configuration
+ */
+export function createMemoryWriteGate(config) {
+    return new MemoryWriteGate(config);
+}
+// ============================================================================
+// Helper: Create a MemoryEntry
+// ============================================================================
+/**
+ * Create a new MemoryEntry with defaults applied
+ */
+export function createMemoryEntry(key, namespace, value, authority, options = {}) {
+    const now = Date.now();
+    return {
+        key,
+        namespace,
+        value,
+        valueHash: computeValueHash(value),
+        authority,
+        createdAt: now,
+        updatedAt: now,
+        ttlMs: options.ttlMs ?? null,
+        decayRate: options.decayRate ?? 0,
+        confidence: options.confidence ?? 1,
+        lineage: options.lineage ?? { operation: 'create' },
+        contradictions: [],
+    };
+}
+//# sourceMappingURL=memory-gate.js.map