rust-kgdb 0.6.81 → 0.6.82

package/hypermind-agent.js

@@ -1642,6 +1642,89 @@ class ProofDAG {
     )
   }
 
+  /**
+   * Add federation query as evidence (HyperFederate cross-database queries)
+   *
+   * Records federated SQL execution across KGDB + Snowflake + BigQuery as
+   * provenance evidence in the proof DAG. Supports full lineage tracking
+   * for cross-database queries with W3C PROV compatibility.
+   *
+   * @param {string} parentId - Parent node ID
+   * @param {string} sql - Federated SQL query
+   * @param {string[]} sources - Data sources involved (e.g., ['kgdb', 'snowflake', 'bigquery'])
+   * @param {number} rowCount - Number of rows returned
+   * @param {number} duration - Query duration in ms
+   * @param {Object} metadata - Additional metadata (planHash, cached, etc.)
+   * @returns {string} New node ID
+   */
+  addFederationEvidence(parentId, sql, sources, rowCount, duration, metadata = {}) {
+    return this.addEvidence(
+      parentId,
+      `Federated query across ${sources.join(', ')} returned ${rowCount} rows in ${duration}ms`,
+      {
+        type: 'federation',
+        sql: sql.slice(0, 500),  // Truncate long queries
+        sources,
+        rowCount,
+        duration,
+        planHash: metadata.planHash,
+        cached: metadata.cached || false,
+        // W3C PROV compatibility
+        wasGeneratedBy: 'hyperfederate:QueryExecution',
+        wasDerivedFrom: sources.map(s => `hyperfederate:DataSource/${s}`)
+      },
+      'FEDERATION_QUERY'
+    )
+  }
+
+  /**
+   * Add virtual table creation as evidence
+   *
+   * @param {string} parentId - Parent node ID
+   * @param {string} tableName - Virtual table name
+   * @param {string} sql - SQL query that defines the virtual table
+   * @param {number} rowCount - Number of rows materialized
+   * @returns {string} New node ID
+   */
+  addVirtualTableEvidence(parentId, tableName, sql, rowCount) {
+    return this.addEvidence(
+      parentId,
+      `Created virtual table '${tableName}' with ${rowCount} rows`,
+      {
+        type: 'virtual_table',
+        tableName,
+        sql: sql.slice(0, 500),
+        rowCount,
+        wasGeneratedBy: 'hyperfederate:VirtualTableCreation'
+      },
+      'VIRTUAL_TABLE_CREATE'
+    )
+  }
+
+  /**
+   * Add catalog registration as evidence
+   *
+   * @param {string} parentId - Parent node ID
+   * @param {string} productName - Data product name
+   * @param {string[]} sources - Data sources
+   * @param {string} productId - Registered product ID
+   * @returns {string} New node ID
+   */
+  addCatalogEvidence(parentId, productName, sources, productId) {
+    return this.addEvidence(
+      parentId,
+      `Registered data product '${productName}' from ${sources.length} sources`,
+      {
+        type: 'catalog',
+        productName,
+        productId,
+        sources,
+        wasGeneratedBy: 'hyperfederate:CatalogRegistration'
+      },
+      'CATALOG_REGISTER'
+    )
+  }
+
   /**
    * Compute deterministic hash of entire proof
    */
@@ -1819,6 +1902,542 @@ const TOOL_REGISTRY = {
     output: 'Distances',
     description: 'Compute shortest paths from landmarks',
     domain: 'kg'
+  },
+
+  // ============================================================================
+  // HyperFederate Federation Tools (Category Theory: Typed Morphisms)
+  // Cross-database federation: KGDB + Snowflake + BigQuery + PostgreSQL + MySQL
+  // ============================================================================
+
+  'federation.sql.query': {
+    name: 'federation.sql.query',
+    input: 'FederatedQuery',
+    output: 'RecordBatch',
+    description: 'Execute federated SQL across KGDB + Snowflake + BigQuery',
+    domain: 'federation',
+    patterns: {
+      cross_join: 'SELECT kg.*, sf.* FROM graph_search(...) kg JOIN snowflake.table sf ON ...',
+      three_way: 'SELECT kg.*, sf.*, bq.* FROM graph_search(...) kg JOIN ... JOIN ...'
+    },
+    connectors: ['kgdb', 'snowflake', 'bigquery', 'postgres', 'mysql']
+  },
+  'federation.virtual.create': {
+    name: 'federation.virtual.create',
+    input: 'VirtualTableSpec',
+    output: 'VirtualTableId',
+    description: 'Create session-bound virtual table from federation query',
+    domain: 'federation'
+  },
+  'federation.virtual.query': {
+    name: 'federation.virtual.query',
+    input: 'VirtualTableQuery',
+    output: 'RecordBatch',
+    description: 'Query existing virtual table',
+    domain: 'federation'
+  },
+  'federation.catalog.list': {
+    name: 'federation.catalog.list',
+    input: 'CatalogFilter',
+    output: 'DataProductList',
+    description: 'List data products in DCAT DPROD catalog',
+    domain: 'federation'
+  },
+  'federation.catalog.register': {
+    name: 'federation.catalog.register',
+    input: 'DataProductSpec',
+    output: 'DataProductId',
+    description: 'Register data product in catalog',
+    domain: 'federation'
+  },
+  'federation.udf.call': {
+    name: 'federation.udf.call',
+    input: 'UdfCall',
+    output: 'UdfResult',
+    description: 'Call semantic UDF (similar_to, neighbors, entity_type, etc.)',
+    domain: 'federation',
+    udfs: ['similar_to', 'text_search', 'neighbors', 'graph_pattern', 'sparql_query', 'entity_type', 'entity_properties']
+  },
+  'federation.table_function.call': {
+    name: 'federation.table_function.call',
+    input: 'TableFunctionCall',
+    output: 'RecordBatch',
+    description: 'Call table function (graph_search, vector_search, pagerank, etc.)',
+    domain: 'federation',
+    functions: ['graph_search', 'vector_search', 'pagerank', 'connected_components', 'shortest_paths', 'triangle_count', 'label_propagation', 'datalog_reason', 'motif_search']
+  }
+}
+
+// Federation tools as separate constant for easy access
+const FEDERATION_TOOLS = {
+  'federation.sql.query': TOOL_REGISTRY['federation.sql.query'],
+  'federation.virtual.create': TOOL_REGISTRY['federation.virtual.create'],
+  'federation.virtual.query': TOOL_REGISTRY['federation.virtual.query'],
+  'federation.catalog.list': TOOL_REGISTRY['federation.catalog.list'],
+  'federation.catalog.register': TOOL_REGISTRY['federation.catalog.register'],
+  'federation.udf.call': TOOL_REGISTRY['federation.udf.call'],
+  'federation.table_function.call': TOOL_REGISTRY['federation.table_function.call']
+}
+
+// ============================================================================
+// RPC FEDERATION PROXY - WASM RPC proxy for HyperFederate
+// ============================================================================
+
+/**
+ * RpcFederationProxy - WASM RPC proxy for HyperFederate cross-database federation
+ *
+ * This follows the same pattern as RpcKgdbStore mentioned in index.js:
+ * "NOTE: QueryMemoryStore, HybridReranker, TriggerManager moved to Rust core
+ *  Access via HyperAgentProxy/WASM runtime (SDK remains thin)"
+ *
+ * Category Theory: Proxy is a natural transformation between local and remote execution
+ * Type Theory: All operations are typed morphisms (Input → Output)
+ * Proof Theory: Full audit log with provenance tracking
+ *
+ * Supports:
+ * - Cross-database SQL: KGDB + Snowflake + BigQuery + PostgreSQL + MySQL
+ * - Virtual Tables: Session-bound query result materialization
+ * - Data Catalog: DCAT DPROD ontology for data product registration
+ * - Semantic UDFs: 7 AI-powered functions (similar_to, neighbors, etc.)
+ * - Table Functions: 9 graph analytics (graph_search, pagerank, etc.)
+ */
+class RpcFederationProxy {
+  /**
+   * Create a new RpcFederationProxy
+   * @param {Object} config - Configuration options
+   * @param {string} config.endpoint - HyperFederate server endpoint (default: http://localhost:30180)
+   * @param {number} config.timeout - Request timeout in ms (default: 30000)
+   * @param {WasmSandbox} config.sandbox - WasmSandbox for capability-based security
+   * @param {Object} config.headers - Additional HTTP headers
+   */
+  constructor(config = {}) {
+    this.endpoint = config.endpoint || 'http://localhost:30180'
+    this.timeout = config.timeout || 30000
+    this.headers = config.headers || {}
+
+    // WasmSandbox for capability-based security with fuel metering
+    // Includes 'Federation' capability for cross-database operations
+    this.sandbox = config.sandbox || new WasmSandbox({
+      capabilities: ['ReadKG', 'ExecuteTool', 'Federation'],
+      fuelLimit: 100000
+    })
+
+    // Audit log for provenance tracking (Proof Theory)
+    this.auditLog = []
+
+    // Session ID for virtual table isolation
+    this.sessionId = config.sessionId || `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+
+    // Identity for access control
+    this.identityId = config.identityId || 'anonymous'
+  }
+
+  /**
+   * Execute federated SQL query across multiple data sources
+   *
+   * Category Theory: FederatedQuery → RecordBatch morphism
+   *
+   * @param {string} sql - Federated SQL query (supports graph_search, snowflake.*, bigquery.*, etc.)
+   * @param {Object} options - Query options
+   * @param {number} options.limit - Result limit
+   * @param {number} options.timeout - Query timeout in ms
+   * @returns {Promise<Object>} RecordBatch result with columns, rows, metadata
+   *
+   * @example
+   * const result = await proxy.query(`
+   *   SELECT kg.person, kg.riskScore, sf.C_NAME, sf.C_ACCTBAL
+   *   FROM graph_search('PREFIX finance: ... SELECT ?person ?riskScore WHERE {...}') kg
+   *   JOIN snowflake_tpch.CUSTOMER sf ON CAST(kg.custKey AS INT) = sf.C_CUSTKEY
+   *   LIMIT 10
+   * `)
+   */
+  async query(sql, options = {}) {
+    // Check capability
+    if (!this.sandbox.hasCapability('Federation')) {
+      throw new Error('Federation capability not granted')
+    }
+
+    // Consume fuel for operation
+    this.sandbox.consumeFuel(1000)
+
+    const start = Date.now()
+
+    try {
+      // RPC call to HyperFederate server
+      const response = await fetch(`${this.endpoint}/api/v1/query`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Session-Id': this.sessionId,
+          'X-Identity-Id': this.identityId,
+          ...this.headers
+        },
+        body: JSON.stringify({
+          sql,
+          limit: options.limit,
+          timeout: options.timeout || this.timeout
+        }),
+        signal: AbortSignal.timeout(options.timeout || this.timeout)
+      })
+
+      if (!response.ok) {
+        const error = await response.text()
+        throw new Error(`Federation query failed: ${error}`)
+      }
+
+      const result = await response.json()
+      const duration = Date.now() - start
+
+      // Log to sandbox audit trail
+      this.sandbox.log('federation.sql.query', { sql: sql.slice(0, 200) }, result, 'success')
+
+      // Add to audit log for provenance
+      this.auditLog.push({
+        action: 'query',
+        sql,
+        duration,
+        rows: result.rows?.length || 0,
+        timestamp: new Date().toISOString(),
+        sessionId: this.sessionId
+      })
+
+      return {
+        columns: result.columns || [],
+        rows: result.rows || [],
+        rowCount: result.rows?.length || 0,
+        duration,
+        metadata: {
+          sources: result.sources || [],
+          planHash: result.planHash,
+          cached: result.cached || false
+        }
+      }
+    } catch (error) {
+      this.sandbox.log('federation.sql.query', { sql: sql.slice(0, 200) }, null, 'error')
+      this.auditLog.push({
+        action: 'query',
+        sql,
+        error: error.message,
+        timestamp: new Date().toISOString(),
+        sessionId: this.sessionId
+      })
+      throw error
+    }
+  }
+
+  /**
+   * Create a virtual table from a federation query result
+   *
+   * Category Theory: VirtualTableSpec → VirtualTableId morphism
+   *
+   * Virtual tables are session-bound, stored as RDF triples in KGDB,
+   * and support access control via shared_with and shared_with_groups.
+   *
+   * @param {string} name - Virtual table name
+   * @param {string} sql - SQL query that defines the virtual table
+   * @param {Object} options - Virtual table options
+   * @param {string} options.refreshPolicy - 'on_demand' | 'ttl' | 'on_source_change'
+   * @param {number} options.ttlSeconds - TTL in seconds (for 'ttl' policy)
+   * @param {string[]} options.sharedWith - Identity IDs to share with
+   * @param {string[]} options.sharedWithGroups - Group IDs to share with
+   * @returns {Promise<Object>} Virtual table metadata
+   *
+   * @example
+   * const vt = await proxy.createVirtualTable('high_risk_customers', `
+   *   SELECT kg.*, sf.C_ACCTBAL
+   *   FROM graph_search('...') kg
+   *   JOIN snowflake.CUSTOMER sf ON ...
+   *   WHERE kg.riskScore > 0.8
+   * `, { refreshPolicy: 'on_demand', ttlSeconds: 3600 })
+   */
+  async createVirtualTable(name, sql, options = {}) {
+    if (!this.sandbox.hasCapability('Federation')) {
+      throw new Error('Federation capability not granted')
+    }
+
+    this.sandbox.consumeFuel(500)
+    const start = Date.now()
+
+    try {
+      const response = await fetch(`${this.endpoint}/api/v1/tables`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Session-Id': this.sessionId,
+          'X-Identity-Id': this.identityId,
+          ...this.headers
+        },
+        body: JSON.stringify({
+          name,
+          sql,
+          refreshPolicy: options.refreshPolicy || 'on_demand',
+          ttlSeconds: options.ttlSeconds || 3600,
+          sharedWith: options.sharedWith || [],
+          sharedWithGroups: options.sharedWithGroups || []
+        }),
+        signal: AbortSignal.timeout(this.timeout)
+      })
+
+      if (!response.ok) {
+        const error = await response.text()
+        throw new Error(`Create virtual table failed: ${error}`)
+      }
+
+      const result = await response.json()
+      const duration = Date.now() - start
+
+      this.sandbox.log('federation.virtual.create', { name, sql: sql.slice(0, 100) }, result, 'success')
+      this.auditLog.push({
+        action: 'createVirtualTable',
+        name,
+        sql,
+        duration,
+        timestamp: new Date().toISOString(),
+        sessionId: this.sessionId
+      })
+
+      return {
+        id: result.id,
+        name: result.name || name,
+        uri: result.uri,
+        columns: result.columns || [],
+        rowCount: result.rowCount,
+        refreshPolicy: options.refreshPolicy || 'on_demand',
+        createdAt: new Date().toISOString()
+      }
+    } catch (error) {
+      this.sandbox.log('federation.virtual.create', { name }, null, 'error')
+      throw error
+    }
+  }
+
+  /**
+   * Query a virtual table
+   *
+   * @param {string} name - Virtual table name
+   * @param {string} whereClauses - Optional WHERE clause conditions
+   * @returns {Promise<Object>} Query result
+   */
+  async queryVirtualTable(name, whereClauses = '') {
+    const sql = `SELECT * FROM virtual.${name}${whereClauses ? ` WHERE ${whereClauses}` : ''}`
+    return this.query(sql)
+  }
+
+  /**
+   * List data products in the DCAT DPROD catalog
+   *
+   * Category Theory: CatalogFilter → DataProductList morphism
+   *
+   * @param {Object} filter - Filter options
+   * @param {string} filter.owner - Filter by owner
+   * @param {string[]} filter.sources - Filter by data sources
+   * @param {string} filter.search - Search in name/description
+   * @returns {Promise<Object[]>} List of data products
+   */
+  async listCatalog(filter = {}) {
+    if (!this.sandbox.hasCapability('ReadKG')) {
+      throw new Error('ReadKG capability not granted')
+    }
+
+    this.sandbox.consumeFuel(100)
+
+    try {
+      const params = new URLSearchParams()
+      if (filter.owner) params.set('owner', filter.owner)
+      if (filter.sources) params.set('sources', filter.sources.join(','))
+      if (filter.search) params.set('search', filter.search)
+
+      const url = `${this.endpoint}/api/v1/catalog${params.toString() ? '?' + params.toString() : ''}`
+
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Session-Id': this.sessionId,
+          'X-Identity-Id': this.identityId,
+          ...this.headers
+        },
+        signal: AbortSignal.timeout(this.timeout)
+      })
+
+      if (!response.ok) {
+        const error = await response.text()
+        throw new Error(`List catalog failed: ${error}`)
+      }
+
+      const result = await response.json()
+      this.sandbox.log('federation.catalog.list', filter, result, 'success')
+
+      return result.products || result
+    } catch (error) {
+      this.sandbox.log('federation.catalog.list', filter, null, 'error')
+      throw error
+    }
+  }
+
+  /**
+   * Register a data product in the DCAT DPROD catalog
+   *
+   * Category Theory: DataProductSpec → DataProductId morphism
+   *
+   * @param {Object} spec - Data product specification
+   * @param {string} spec.name - Product name
+   * @param {string} spec.description - Product description
+   * @param {string[]} spec.sources - Data source identifiers
+   * @param {string} spec.outputPort - API endpoint for querying
+   * @param {Object} spec.schema - Column schema definition
+   * @param {Object} spec.quality - Quality metrics (completeness, accuracy)
+   * @param {string} spec.owner - Owner identity
+   * @returns {Promise<Object>} Registered data product with ID
+   *
+   * @example
+   * const product = await proxy.registerDataProduct({
+   *   name: 'High Risk Customer Analysis',
+   *   description: 'Cross-domain risk scoring combining KG + transactional data',
+   *   sources: ['kgdb', 'snowflake', 'bigquery'],
+   *   outputPort: '/api/v1/products/high-risk/query',
+   *   schema: { columns: [{ name: 'entity', type: 'STRING' }, ...] },
+   *   quality: { completeness: 0.98, accuracy: 0.95 },
+   *   owner: 'risk-analytics-team'
+   * })
+   */
+  async registerDataProduct(spec) {
+    if (!this.sandbox.hasCapability('Federation')) {
+      throw new Error('Federation capability not granted')
+    }
+
+    this.sandbox.consumeFuel(500)
+
+    try {
+      const response = await fetch(`${this.endpoint}/api/v1/catalog`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Session-Id': this.sessionId,
+          'X-Identity-Id': this.identityId,
+          ...this.headers
+        },
+        body: JSON.stringify(spec),
+        signal: AbortSignal.timeout(this.timeout)
+      })
+
+      if (!response.ok) {
+        const error = await response.text()
+        throw new Error(`Register data product failed: ${error}`)
+      }
+
+      const result = await response.json()
+      this.sandbox.log('federation.catalog.register', { name: spec.name }, result, 'success')
+
+      this.auditLog.push({
+        action: 'registerDataProduct',
+        name: spec.name,
+        sources: spec.sources,
+        timestamp: new Date().toISOString(),
+        sessionId: this.sessionId
+      })
+
+      return {
+        id: result.id,
+        uri: result.uri,
+        name: spec.name,
+        createdAt: new Date().toISOString()
+      }
+    } catch (error) {
+      this.sandbox.log('federation.catalog.register', { name: spec.name }, null, 'error')
+      throw error
+    }
+  }
+
+  /**
+   * Call a semantic UDF (one of 7 AI-powered functions)
+   *
+   * Available UDFs:
+   * - similar_to(entity, threshold) - Find semantically similar entities via RDF2Vec
+   * - text_search(query, limit) - Semantic text search
+   * - neighbors(entity, hops) - N-hop graph traversal
+   * - graph_pattern(s, p, o) - Triple pattern matching
+   * - sparql_query(sparql) - Inline SPARQL execution
+   * - entity_type(entity) - Get RDF types
+   * - entity_properties(entity) - Get all properties
+   *
+   * @param {string} udfName - UDF function name
+   * @param {Array} args - UDF arguments
+   * @returns {Promise<Object>} UDF result
+   */
+  async callUdf(udfName, ...args) {
+    const validUdfs = ['similar_to', 'text_search', 'neighbors', 'graph_pattern', 'sparql_query', 'entity_type', 'entity_properties']
+    if (!validUdfs.includes(udfName)) {
+      throw new Error(`Unknown UDF: ${udfName}. Valid UDFs: ${validUdfs.join(', ')}`)
+    }
+
+    // Build SQL with UDF call
+    const argsStr = args.map(a => typeof a === 'string' ? `'${a}'` : a).join(', ')
+    const sql = `SELECT ${udfName}(${argsStr}) AS result`
+
+    return this.query(sql)
+  }
+
+  /**
+   * Call a table function (one of 9 graph analytics functions)
+   *
+   * Available table functions:
+   * - graph_search(sparql) - SPARQL → SQL bridge
+   * - vector_search(text, k, threshold) - Semantic similarity search
+   * - pagerank(sparql, damping, iterations) - PageRank centrality
+   * - connected_components(sparql) - Community detection
+   * - shortest_paths(src, dst, max_hops) - Path finding
+   * - triangle_count(sparql) - Graph density measure
+   * - label_propagation(sparql, iterations) - Community detection
+   * - datalog_reason(rules) - Datalog inference
+   * - motif_search(pattern) - Graph pattern matching
+   *
+   * @param {string} functionName - Table function name
+   * @param {Array} args - Function arguments
+   * @returns {Promise<Object>} RecordBatch result
+   */
+  async callTableFunction(functionName, ...args) {
+    const validFunctions = ['graph_search', 'vector_search', 'pagerank', 'connected_components', 'shortest_paths', 'triangle_count', 'label_propagation', 'datalog_reason', 'motif_search']
+    if (!validFunctions.includes(functionName)) {
+      throw new Error(`Unknown table function: ${functionName}. Valid functions: ${validFunctions.join(', ')}`)
+    }
+
+    const argsStr = args.map(a => typeof a === 'string' ? `'${a}'` : a).join(', ')
+    const sql = `SELECT * FROM ${functionName}(${argsStr})`
+
+    return this.query(sql)
+  }
+
+  /**
+   * Get the audit log for provenance tracking
+   *
+   * @returns {Array<Object>} Audit log entries
+   */
+  getAuditLog() {
+    return [...this.auditLog]
+  }
+
+  /**
+   * Clear the audit log
+   */
+  clearAuditLog() {
+    this.auditLog = []
+  }
+
+  /**
+   * Get sandbox fuel remaining
+   * @returns {number} Fuel remaining
+   */
+  getFuelRemaining() {
+    return this.sandbox.fuel
+  }
+
+  /**
+   * Check if a capability is granted
+   * @param {string} capability - Capability name
+   * @returns {boolean} True if capability is granted
+   */
+  hasCapability(capability) {
+    return this.sandbox.hasCapability(capability)
   }
 }
 
@@ -4845,6 +5464,13 @@ module.exports = {
   LLMPlanner,
   TOOL_REGISTRY,
 
+  // HyperFederate (v0.7.0+) - Cross-Database Federation
+  // Query across KGDB + Snowflake + BigQuery in single SQL
+  // Category Theory: Tools as typed morphisms (Input → Output)
+  // Proof Theory: Full lineage tracking with W3C PROV
+  RpcFederationProxy,    // WASM RPC proxy for federated queries
+  FEDERATION_TOOLS,      // 7 federation tools as typed morphisms
+
   // Context Theory (v0.6.11+) - Type-theoretic foundations for SPARQL validation
   // Based on: Spivak's Ologs, Functorial Data Migration, TypeQL
   SchemaContext,    // Γ context with classes, properties, bindings