network-ai 5.10.1 → 5.11.0

package/dist/esm/lib/semantic-search.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Semantic Memory Search — Embeddings-based retrieval over blackboard data
+ *
+ * Provides an in-memory vector store that can index blackboard entries and
+ * answer similarity queries. Bring your own embedding function (BYOE) —
+ * no runtime dependency on any specific model or provider.
+ *
+ * Optionally persists the index to a JSON file (`persistPath`) so memory
+ * survives process restarts without re-embedding everything.
+ *
+ * Inspired by Claw-Code's semantic memory pattern.
+ *
+ * @module SemanticSearch
+ * @version 1.1.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticMemory = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ============================================================================
+// MATH HELPERS
+// ============================================================================
+/**
+ * Cosine similarity between two equal-length vectors.
+ * Returns 0 for zero-magnitude vectors.
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ============================================================================
+// SEMANTIC MEMORY
+// ============================================================================
+/**
+ * In-memory semantic vector store with optional file-backed persistence.
+ *
+ * @example
+ * ```typescript
+ * // Ephemeral (in-memory only)
+ * const memory = new SemanticMemory(async (text) => openai.embed(text));
+ *
+ * // Persistent across restarts
+ * const memory = new SemanticMemory(
+ *   async (text) => openai.embed(text),
+ *   { persistPath: './data/semantic-index.json' }
+ * );
+ * await memory.load(); // restore from disk on startup
+ *
+ * // Index entries
+ * await memory.index('task:1', 'Quarterly revenue analysis', { status: 'done' }, 'analyst');
+ * await memory.save(); // flush to disk
+ *
+ * // Search
+ * const results = await memory.search('financial trends', 5);
+ * // → [{ key: 'task:1', score: 0.87, ... }]
+ * ```
+ */
+class SemanticMemory {
+    entries = new Map();
+    embeddingFn;
+    persistPath;
+    /**
+     * @param embeddingFn  Function that produces embeddings from text
+     * @param options      Optional configuration
+     * @param options.persistPath  Path to a JSON file for durable storage.
+     *   Call `load()` after construction to restore, and `save()` (or use
+     *   `autoSave`) to flush writes.
+     */
+    constructor(embeddingFn, options) {
+        this.embeddingFn = embeddingFn;
+        this.persistPath = options?.persistPath ? (0, path_1.resolve)(options.persistPath) : undefined;
+    }
+    // --------------------------------------------------------------------------
+    // Persistence
+    // --------------------------------------------------------------------------
+    /**
+     * Persist the current in-memory index to `persistPath`.
+     * No-op when `persistPath` was not set.
+     */
+    save() {
+        if (!this.persistPath)
+            return;
+        try {
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(this.persistPath), { recursive: true });
+            const data = {
+                version: 1,
+                savedAt: new Date().toISOString(),
+                entries: Array.from(this.entries.values()),
+            };
+            (0, fs_1.writeFileSync)(this.persistPath, JSON.stringify(data), 'utf-8');
+        }
+        catch { /* non-fatal */ }
+    }
+    /**
+     * Restore the index from `persistPath`.
+     * No-op when `persistPath` was not set or the file does not exist.
+     *
+     * Call this once after construction to warm the index from a previous run.
+     */
+    load() {
+        if (!this.persistPath || !(0, fs_1.existsSync)(this.persistPath))
+            return;
+        try {
+            const raw = (0, fs_1.readFileSync)(this.persistPath, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data.version !== 1 || !Array.isArray(data.entries))
+                return;
+            this.entries.clear();
+            for (const entry of data.entries) {
+                if (typeof entry.key === 'string' &&
+                    Array.isArray(entry.embedding) &&
+                    entry.embedding.length > 0) {
+                    this.entries.set(entry.key, entry);
+                }
+            }
+        }
+        catch { /* non-fatal — start with empty index */ }
+    }
+    /**
+     * Delete the persistence file.
+     * Useful for clearing stale indexes between projects.
+     */
+    clearPersisted() {
+        if (!this.persistPath || !(0, fs_1.existsSync)(this.persistPath))
+            return;
+        try {
+            const { unlinkSync } = require('fs');
+            unlinkSync(this.persistPath);
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Index a key–value pair with its text representation.
+     * Re-indexing the same key replaces the previous embedding.
+     *
+     * @param key Unique identifier
+     * @param text The text to embed for similarity matching
+     * @param value The value to return in search results
+     * @param sourceAgent Agent that produced this entry
+     * @param autoSave Flush to disk after indexing (requires `persistPath`). Default false.
+     */
+    async index(key, text, value, sourceAgent, autoSave = false) {
+        const embedding = await this.embeddingFn(text);
+        this.entries.set(key, { key, text, value, sourceAgent, embedding });
+        if (autoSave)
+            this.save();
+    }
+    /**
+     * Search for entries similar to the query text.
+     *
+     * @param query Natural language query
+     * @param topK Maximum results to return (default 5)
+     * @param threshold Minimum cosine similarity (default 0)
+     * @returns Sorted results, highest similarity first
+     */
+    async search(query, topK = 5, threshold = 0) {
+        if (this.entries.size === 0)
+            return [];
+        const queryEmbedding = await this.embeddingFn(query);
+        const scored = [];
+        for (const entry of this.entries.values()) {
+            const score = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (score >= threshold) {
+                scored.push({
+                    key: entry.key,
+                    value: entry.value,
+                    score,
+                    sourceAgent: entry.sourceAgent,
+                });
+            }
+        }
+        // Sort descending by score, take top-K
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, topK);
+    }
+    /**
+     * Bulk-index all entries from a blackboard snapshot.
+     *
+     * @param snapshot Record of key → { value, source_agent } (from LockedBlackboard.getSnapshot())
+     * @returns Number of entries indexed
+     */
+    async indexSnapshot(snapshot) {
+        let count = 0;
+        for (const [key, entry] of Object.entries(snapshot)) {
+            const text = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
+            await this.index(key, text, entry.value, entry.source_agent);
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Remove an entry by key.
+     * @returns true if an entry was removed
+     */
+    remove(key) {
+        return this.entries.delete(key);
+    }
+    /**
+     * Remove all indexed entries.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Number of indexed entries.
+     */
+    size() {
+        return this.entries.size;
+    }
+    /**
+     * Check if a key is indexed.
+     */
+    has(key) {
+        return this.entries.has(key);
+    }
+    /**
+     * List all indexed keys.
+     */
+    keys() {
+        return Array.from(this.entries.keys());
+    }
+}
+exports.SemanticMemory = SemanticMemory;
+//# sourceMappingURL=semantic-search.js.map

package/dist/esm/lib/semantic-search.js.map

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

package/dist/esm/lib/shared-blackboard.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Namespace-scoped, identity-verified shared state for multi-agent coordination.
+ *
+ * Every write is identity-verified (agent token), namespace-checked,
+ * size-validated, input-sanitized, and atomically persisted through
+ * the pluggable {@link BlackboardBackend}.
+ *
+ * @module SharedBlackboard
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedBlackboard = void 0;
+const blackboard_backend_1 = require("./blackboard-backend");
+const security_1 = require("../security");
+const errors_1 = require("./errors");
+const orchestrator_types_1 = require("./orchestrator-types");
+/**
+ * Namespace-scoped, identity-verified shared state for multi-agent coordination.
+ *
+ * Every write is identity-verified (agent token), namespace-checked,
+ * size-validated, input-sanitized, and atomically persisted through
+ * {@link LockedBlackboard}.
+ *
+ * @example
+ * ```typescript
+ * const bb = new SharedBlackboard('./workspace');
+ * bb.registerAgent('analyst', 'secret-token', ['task:', 'analytics:']);
+ * bb.write('task:revenue', { q4: 42_000 }, 'analyst', 3600, 'secret-token');
+ * const entry = bb.read('task:revenue');
+ * ```
+ */
+class SharedBlackboard {
+    backend;
+    agentTokens = new Map(); // agentId -> verified token
+    agentNamespaces = new Map(); // agentId -> allowed prefixes
+    piiRedactor = null;
+    constructor(backendOrPath, options) {
+        if (typeof backendOrPath === 'string') {
+            if (!backendOrPath || backendOrPath.trim() === '') {
+                throw new errors_1.ValidationError('basePath must be a non-empty string');
+            }
+            this.backend = new blackboard_backend_1.FileBackend(backendOrPath);
+        }
+        else {
+            if (!backendOrPath || typeof backendOrPath !== 'object') {
+                throw new errors_1.ValidationError('backend must be a BlackboardBackend instance');
+            }
+            this.backend = backendOrPath;
+        }
+        if (options?.enablePIIRedaction) {
+            this.piiRedactor = new security_1.PIIRedactor();
+        }
+    }
+    /**
+     * Enable or disable PII redaction on writes.
+     */
+    setPIIRedaction(enabled) {
+        this.piiRedactor = enabled ? new security_1.PIIRedactor() : null;
+    }
+    /**
+     * Register a verified agent identity. Only agents with registered tokens
+     * can write to the blackboard. The orchestrator registers agents after
+     * verifying their identity through the AuthGuardian.
+     */
+    registerAgent(agentId, verificationToken, allowedNamespaces = ['*']) {
+        if (!agentId || typeof agentId !== 'string' || agentId.trim() === '') {
+            throw new errors_1.ValidationError('agentId must be a non-empty string');
+        }
+        if (!verificationToken || typeof verificationToken !== 'string') {
+            throw new errors_1.ValidationError('verificationToken must be a non-empty string');
+        }
+        if (!Array.isArray(allowedNamespaces)) {
+            throw new errors_1.ValidationError('allowedNamespaces must be an array of strings');
+        }
+        this.agentTokens.set(agentId, verificationToken);
+        this.agentNamespaces.set(agentId, allowedNamespaces);
+    }
+    /**
+     * Check if an agent is allowed to access a key based on namespace rules.
+     */
+    canAccessKey(agentId, key) {
+        const namespaces = this.agentNamespaces.get(agentId);
+        if (!namespaces)
+            return false;
+        if (namespaces.includes('*'))
+            return true;
+        return namespaces.some(ns => key.startsWith(ns));
+    }
+    /**
+     * Verify that the calling agent is who they claim to be.
+     */
+    verifyAgent(agentId, token) {
+        const registeredToken = this.agentTokens.get(agentId);
+        // If no token system is configured for this agent, allow (backward compat)
+        if (!registeredToken)
+            return true;
+        return token === registeredToken;
+    }
+    /**
+     * Validate value size and structure before writing.
+     * Prevents DoS via oversized writes and circular data.
+     */
+    validateValue(value) {
+        try {
+            const serialized = JSON.stringify(value);
+            if (serialized.length > orchestrator_types_1.CONFIG.maxBlackboardValueSize) {
+                return { valid: false, reason: `Value exceeds max size (${serialized.length} > ${orchestrator_types_1.CONFIG.maxBlackboardValueSize} bytes)` };
+            }
+            return { valid: true };
+        }
+        catch {
+            return { valid: false, reason: 'Value cannot be serialized (circular reference or invalid structure)' };
+        }
+    }
+    /**
+     * Sanitize a key to prevent markdown injection.
+     */
+    sanitizeKey(key) {
+        // Keys must be safe for markdown headings -- no #, newlines, or markdown syntax
+        return key.replace(/[#\n\r|`]/g, '_').slice(0, 256);
+    }
+    /**
+     * Read an entry from the blackboard by key.
+     *
+     * @param key - The entry key to look up
+     * @returns The entry, or `null` if not found or expired
+     * @throws {@link ValidationError} if `key` is not a non-empty string
+     */
+    read(key) {
+        if (!key || typeof key !== 'string') {
+            throw new errors_1.ValidationError('key must be a non-empty string');
+        }
+        const entry = this.backend.read(key);
+        if (!entry)
+            return null;
+        // Normalize field name for backward compatibility
+        return {
+            key: entry.key,
+            value: entry.value,
+            sourceAgent: entry.source_agent ?? entry.sourceAgent ?? 'unknown',
+            timestamp: entry.timestamp,
+            ttl: entry.ttl,
+        };
+    }
+    /**
+     * Write to the blackboard with identity verification, namespace checks,
+     * value validation, and input sanitization. Uses LockedBlackboard for
+     * atomic file-system writes.
+     *
+     * @param key - The key to write
+     * @param value - The value (will be sanitized and size-checked)
+     * @param sourceAgent - Agent claiming to write (verified against registered token)
+     * @param ttl - Optional TTL in seconds
+     * @param agentToken - Optional verification token for identity check
+     */
+    write(key, value, sourceAgent, ttl, agentToken) {
+        // 1. Verify agent identity
+        if (!this.verifyAgent(sourceAgent, agentToken)) {
+            throw new errors_1.IdentityVerificationError(sourceAgent);
+        }
+        // 2. Namespace check
+        if (!this.canAccessKey(sourceAgent, key)) {
+            throw new errors_1.NamespaceViolationError(sourceAgent, key);
+        }
+        // 3. Sanitize key
+        const safeKey = this.sanitizeKey(key);
+        // 4. Validate value size/structure
+        const validation = this.validateValue(value);
+        if (!validation.valid) {
+            throw new errors_1.ValidationError(validation.reason);
+        }
+        // 5. Sanitize value -- strip injection payloads from string content
+        let sanitizedValue;
+        try {
+            sanitizedValue = security_1.InputSanitizer.sanitizeObject(value);
+        }
+        catch {
+            sanitizedValue = value; // Fall back to raw if sanitization can't handle it
+        }
+        // 5b. PII redaction -- strip emails, SSNs, credit cards, phones, IPs
+        if (this.piiRedactor) {
+            const { redacted } = this.piiRedactor.redactObject(sanitizedValue);
+            sanitizedValue = redacted;
+        }
+        // 6. Write through backend (atomic when using FileBackend; in-memory for MemoryBackend)
+        const entry = this.backend.write(safeKey, sanitizedValue, sourceAgent, ttl);
+        // Normalize for backward compat
+        return {
+            key: entry.key,
+            value: entry.value,
+            sourceAgent: entry.source_agent ?? sourceAgent,
+            timestamp: entry.timestamp,
+            ttl: entry.ttl,
+        };
+    }
+    /**
+     * Check whether a key exists on the blackboard (not expired).
+     * @param key - The entry key to check
+     */
+    exists(key) {
+        return this.read(key) !== null;
+    }
+    /**
+     * Get a full snapshot of all blackboard entries.
+     */
+    getSnapshot() {
+        const raw = this.backend.getSnapshot();
+        const normalized = {};
+        for (const [key, entry] of Object.entries(raw)) {
+            normalized[key] = {
+                key: entry.key,
+                value: entry.value,
+                sourceAgent: entry.source_agent ?? entry.sourceAgent ?? 'unknown',
+                timestamp: entry.timestamp,
+                ttl: entry.ttl,
+            };
+        }
+        return normalized;
+    }
+    /**
+     * Get a namespace-scoped snapshot -- only returns keys an agent is allowed to see.
+     * Prevents data leakage between agents.
+     */
+    getScopedSnapshot(agentId) {
+        if (!agentId || typeof agentId !== 'string') {
+            throw new errors_1.ValidationError('agentId must be a non-empty string');
+        }
+        const full = this.getSnapshot();
+        const scoped = {};
+        for (const [key, entry] of Object.entries(full)) {
+            if (this.canAccessKey(agentId, key)) {
+                scoped[key] = entry;
+            }
+        }
+        return scoped;
+    }
+    /**
+     * Clear all entries (for testing).
+     */
+    clear() {
+        // Write an empty state through locked backend
+        const keys = this.backend.listKeys();
+        for (const key of keys) {
+            this.backend.delete(key);
+        }
+    }
+}
+exports.SharedBlackboard = SharedBlackboard;
+//# sourceMappingURL=shared-blackboard.js.map

package/dist/esm/lib/shared-blackboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-blackboard.js","sourceRoot":"","sources":["../../../lib/shared-blackboard.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,6DAAmD;AAEnD,0CAA0D;AAC1D,qCAIkB;AAClB,6DAA8C;AAG9C;;;;;;;;;;;;;;GAcG;AACH,MAAa,gBAAgB;IACnB,OAAO,CAAoB;IAC3B,WAAW,GAAwB,IAAI,GAAG,EAAE,CAAC,CAAC,4BAA4B;IAC1E,eAAe,GAA0B,IAAI,GAAG,EAAE,CAAC,CAAC,8BAA8B;IAClF,WAAW,GAAuB,IAAI,CAAC;IAE/C,YAAY,aAAyC,EAAE,OAA0C;QAC/F,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAClD,MAAM,IAAI,wBAAe,CAAC,qCAAqC,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,gCAAW,CAAC,aAAa,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;gBACxD,MAAM,IAAI,wBAAe,CAAC,8CAA8C,CAAC,CAAC;YAC5E,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC;QAC/B,CAAC;QACD,IAAI,OAAO,EAAE,kBAAkB,EAAE,CAAC;YAChC,IAAI,CAAC,WAAW,GAAG,IAAI,sBAAW,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,OAAgB;QAC9B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,sBAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,OAAe,EAAE,iBAAyB,EAAE,oBAA8B,CAAC,GAAG,CAAC;QAC3F,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACrE,MAAM,IAAI,wBAAe,CAAC,oCAAoC,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,CAAC,iBAAiB,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;YAChE,MAAM,IAAI,wBAAe,CAAC,8CAA8C,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,wBAAe,CAAC,+CAA+C,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACjD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,OAAe,EAAE,GAAW;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAC9B,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,OAAe,EAAE,KAAc;QACjD,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtD,2EAA2E;QAC3E,IAAI,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QAClC,OAAO,KAAK,KAAK,eAAe,CAAC;IACnC,CAAC;IAED;;;OAGG;IACK,aAAa,CAAC,KAAc;QAClC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,UAAU,CAAC,MAAM,GAAG,2BAAM,CAAC,sBAAsB,EAAE,CAAC;gBACtD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,UAAU,CAAC,MAAM,MAAM,2BAAM,CAAC,sBAAsB,SAAS,EAAE,CAAC;YAC5H,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,sEAAsE,EAAE,CAAC;QAC1G,CAAC;IACH,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,GAAW;QAC7B,gFAAgF;QAChF,OAAO,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,GAAW;QACd,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,wBAAe,CAAC,gCAAgC,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,kDAAkD;QAClD,OAAO;YACL,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAG,KAAa,CAAC,YAAY,IAAK,KAAa,CAAC,WAAW,IAAI,SAAS;YACnF,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAW,EAAE,KAAc,EAAE,WAAmB,EAAE,GAAY,EAAE,UAAmB;QACvF,2BAA2B;QAC3B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,kCAAyB,CAAC,WAAW,CAAC,CAAC;QACnD,CAAC;QAED,qBAAqB;QACrB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,gCAAuB,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;QAED,kBAAkB;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAEtC,mCAAmC;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,IAAI,wBAAe,CAAC,UAAU,CAAC,MAAO,CAAC,CAAC;QAChD,CAAC;QAED,oEAAoE;QACpE,IAAI,cAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,cAAc,GAAG,yBAAc,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,cAAc,GAAG,KAAK,CAAC,CAAC,mDAAmD;QAC7E,CAAC;QAED,qEAAqE;QACrE,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;YACnE,cAAc,GAAG,QAAQ,CAAC;QAC5B,CAAC;QAED,wFAAwF;QACxF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QAE5E,gCAAgC;QAChC,OAAO;YACL,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAG,KAAa,CAAC,YAAY,IAAI,WAAW;YACvD,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,UAAU,GAAoC,EAAE,CAAC;QACvD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,UAAU,CAAC,GAAG,CAAC,GAAG;gBAChB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAG,KAAa,CAAC,YAAY,IAAK,KAAa,CAAC,WAAW,IAAI,SAAS;gBACnF,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC;QACJ,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,OAAe;QAC/B,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,wBAAe,CAAC,oCAAoC,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,MAAM,MAAM,GAAoC,EAAE,CAAC;QACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,8CAA8C;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;CACF;AApOD,4CAoOC"}