rust-kgdb 0.6.81 → 0.6.82

package/index.d.ts

@@ -895,6 +895,310 @@ export interface ToolMorphism {
  */
 export const TOOL_REGISTRY: Record<string, ToolMorphism>
 
+/**
+ * FEDERATION_TOOLS - HyperFederate federation tools as typed morphisms
+ *
+ * 7 tools for cross-database queries:
+ * - federation.sql.query: Execute federated SQL across KGDB + Snowflake + BigQuery
+ * - federation.virtual.create: Create session-bound virtual table
+ * - federation.virtual.query: Query existing virtual table
+ * - federation.catalog.list: List data products in DCAT DPROD catalog
+ * - federation.catalog.register: Register data product
+ * - federation.udf.call: Call semantic UDF (similar_to, neighbors, etc.)
+ * - federation.table_function.call: Call table function (graph_search, pagerank, etc.)
+ */
+export const FEDERATION_TOOLS: Record<string, ToolMorphism>
+
+// ============================================================================
+// HyperFederate (v0.7.0+) - Cross-Database Federation
+// ============================================================================
+
+/**
+ * Federation configuration for RpcFederationProxy
+ */
+export interface FederationConfig {
+  /** HyperFederate server endpoint (default: http://localhost:30180) */
+  endpoint?: string
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number
+  /** WasmSandbox for capability-based security */
+  sandbox?: WasmSandbox
+  /** Additional HTTP headers */
+  headers?: Record<string, string>
+  /** Session ID for virtual table isolation */
+  sessionId?: string
+  /** Identity ID for access control */
+  identityId?: string
+}
+
+/**
+ * Virtual table specification for createVirtualTable
+ */
+export interface VirtualTableSpec {
+  /** Refresh policy: 'on_demand' | 'ttl' | 'on_source_change' */
+  refreshPolicy?: 'on_demand' | 'ttl' | 'on_source_change'
+  /** TTL in seconds (for 'ttl' policy) */
+  ttlSeconds?: number
+  /** Identity IDs to share with */
+  sharedWith?: string[]
+  /** Group IDs to share with */
+  sharedWithGroups?: string[]
+}
+
+/**
+ * Virtual table metadata returned by createVirtualTable
+ */
+export interface VirtualTableMetadata {
+  id: string
+  name: string
+  uri?: string
+  columns: string[]
+  rowCount?: number
+  refreshPolicy: string
+  createdAt: string
+}
+
+/**
+ * Data product specification for registerDataProduct
+ */
+export interface DataProductSpec {
+  /** Product name */
+  name: string
+  /** Product description */
+  description: string
+  /** Data source identifiers (e.g., ['kgdb', 'snowflake', 'bigquery']) */
+  sources: string[]
+  /** API endpoint for querying */
+  outputPort: string
+  /** Column schema definition */
+  schema: {
+    columns: Array<{ name: string; type: string }>
+  }
+  /** Quality metrics */
+  quality?: {
+    completeness?: number
+    accuracy?: number
+  }
+  /** Owner identity */
+  owner: string
+}
+
+/**
+ * RecordBatch result from federated queries
+ */
+export interface RecordBatch {
+  columns: string[]
+  rows: Record<string, unknown>[]
+  rowCount: number
+  duration?: number
+  metadata?: {
+    sources?: string[]
+    planHash?: string
+    cached?: boolean
+  }
+}
+
+/**
+ * Audit log entry for provenance tracking
+ */
+export interface FederationAuditEntry {
+  action: string
+  sql?: string
+  name?: string
+  duration?: number
+  rows?: number
+  error?: string
+  timestamp: string
+  sessionId: string
+  sources?: string[]
+}
+
+/**
+ * RpcFederationProxy - WASM RPC proxy for HyperFederate cross-database federation
+ *
+ * Enables querying across KGDB + Snowflake + BigQuery in single SQL statements.
+ * Uses capability-based security via WasmSandbox with fuel metering.
+ *
+ * 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 W3C PROV provenance tracking
+ *
+ * @example
+ * ```typescript
+ * const federation = new RpcFederationProxy({
+ *   endpoint: 'http://localhost:30180',
+ *   identityId: 'risk-analyst-001'
+ * })
+ *
+ * // Three-way federation query
+ * const result = await federation.query(`
+ *   SELECT kg.person, kg.riskScore, sf.C_NAME, bq.total_births
+ *   FROM graph_search('PREFIX finance: ... SELECT ?person ?riskScore WHERE {...}') kg
+ *   JOIN snowflake_tpch.CUSTOMER sf ON CAST(kg.custKey AS INT) = sf.C_CUSTKEY
+ *   LEFT JOIN bigquery_public.usa_names bq ON LOWER(SPLIT(sf.C_NAME, ' ')[0]) = LOWER(bq.name)
+ *   LIMIT 10
+ * `)
+ * ```
+ */
+export class RpcFederationProxy {
+  /** HyperFederate server endpoint */
+  endpoint: string
+  /** Request timeout in ms */
+  timeout: number
+  /** WasmSandbox for capability-based security */
+  sandbox: WasmSandbox
+  /** Audit log for provenance tracking */
+  auditLog: FederationAuditEntry[]
+  /** Session ID for virtual table isolation */
+  sessionId: string
+  /** Identity ID for access control */
+  identityId: string
+
+  constructor(config?: FederationConfig)
+
+  /**
+   * Execute federated SQL query across multiple data sources
+   *
+   * @param sql - Federated SQL query (supports graph_search, snowflake.*, bigquery.*, etc.)
+   * @param options - Query options (limit, timeout)
+   * @returns RecordBatch result with columns, rows, metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await federation.query(`
+   *   SELECT kg.entity, kg.riskScore, sf.C_ACCTBAL
+   *   FROM graph_search('...') kg
+   *   JOIN snowflake.CUSTOMER sf ON ...
+   * `)
+   * console.log(result.rows)
+   * ```
+   */
+  query(sql: string, options?: { limit?: number; timeout?: number }): Promise<RecordBatch>
+
+  /**
+   * Create a virtual table from a federation query result
+   *
+   * Virtual tables are session-bound, stored as RDF triples in KGDB,
+   * and support access control via shared_with and shared_with_groups.
+   *
+   * @param name - Virtual table name
+   * @param sql - SQL query that defines the virtual table
+   * @param options - Virtual table options
+   * @returns Virtual table metadata
+   *
+   * @example
+   * ```typescript
+   * const vt = await federation.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 })
+   * ```
+   */
+  createVirtualTable(name: string, sql: string, options?: VirtualTableSpec): Promise<VirtualTableMetadata>
+
+  /**
+   * Query a virtual table
+   *
+   * @param name - Virtual table name
+   * @param whereClauses - Optional WHERE clause conditions
+   * @returns Query result
+   */
+  queryVirtualTable(name: string, whereClauses?: string): Promise<RecordBatch>
+
+  /**
+   * List data products in the DCAT DPROD catalog
+   *
+   * @param filter - Filter options (owner, sources, search)
+   * @returns List of data products
+   */
+  listCatalog(filter?: { owner?: string; sources?: string[]; search?: string }): Promise<DataProductSpec[]>
+
+  /**
+   * Register a data product in the DCAT DPROD catalog
+   *
+   * @param spec - Data product specification
+   * @returns Registered data product with ID
+   *
+   * @example
+   * ```typescript
+   * const product = await federation.registerDataProduct({
+   *   name: 'High Risk Customer Analysis',
+   *   description: 'Cross-domain risk scoring',
+   *   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'
+   * })
+   * ```
+   */
+  registerDataProduct(spec: DataProductSpec): Promise<{ id: string; uri?: string; name: string; createdAt: string }>
+
+  /**
+   * Call a semantic UDF (one of 7 AI-powered functions)
+   *
+   * Available UDFs:
+   * - similar_to(entity, threshold) - Find 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 udfName - UDF function name
+   * @param args - UDF arguments
+   * @returns UDF result
+   */
+  callUdf(udfName: string, ...args: unknown[]): Promise<RecordBatch>
+
+  /**
+   * Call a table function (one of 9 graph analytics functions)
+   *
+   * Available functions:
+   * - graph_search(sparql) - SPARQL → SQL bridge
+   * - vector_search(text, k, threshold) - Semantic similarity
+   * - pagerank(sparql, damping, iterations) - PageRank centrality
+   * - connected_components(sparql) - Community detection
+   * - shortest_paths(src, dst, max_hops) - Path finding
+   * - triangle_count(sparql) - Graph density
+   * - label_propagation(sparql, iterations) - Community detection
+   * - datalog_reason(rules) - Datalog inference
+   * - motif_search(pattern) - Graph pattern matching
+   *
+   * @param functionName - Table function name
+   * @param args - Function arguments
+   * @returns RecordBatch result
+   */
+  callTableFunction(functionName: string, ...args: unknown[]): Promise<RecordBatch>
+
+  /**
+   * Get the audit log for provenance tracking
+   * @returns Audit log entries
+   */
+  getAuditLog(): FederationAuditEntry[]
+
+  /**
+   * Clear the audit log
+   */
+  clearAuditLog(): void
+
+  /**
+   * Get sandbox fuel remaining
+   * @returns Fuel remaining
+   */
+  getFuelRemaining(): number
+
+  /**
+   * Check if a capability is granted
+   * @param capability - Capability name
+   * @returns True if capability is granted
+   */
+  hasCapability(capability: string): boolean
+}
+
 /**
  * LLMPlanner - Natural language to typed tool pipelines
  *

package/index.js

@@ -79,6 +79,10 @@ const {
   // LLM Planning (v0.6.7+) - Natural Language to Typed Tools
   LLMPlanner,
   TOOL_REGISTRY,
+  // HyperFederate (v0.7.0+) - Cross-Database Federation via WASM RPC
+  // Query across KGDB + Snowflake + BigQuery in single SQL
+  RpcFederationProxy,
+  FEDERATION_TOOLS,
   // Type System (v0.6.7+)
   TypeId,
   // Memory Layer (v0.5.13+) - GraphDB-Powered Agent Memory
@@ -147,6 +151,11 @@ module.exports = {
   // LLM Planning (v0.6.7+) - Natural Language to Typed Tools
   LLMPlanner,
   TOOL_REGISTRY,
+  // HyperFederate (v0.7.0+) - Cross-Database Federation
+  // Query across KGDB + Snowflake + BigQuery in single SQL statement
+  // Supports: 7 Semantic UDFs + 9 Table Functions + Virtual Tables + DCAT Catalog
+  RpcFederationProxy,    // WASM RPC proxy for federated queries
+  FEDERATION_TOOLS,      // 7 federation tools as typed morphisms
   // Type System (v0.6.7+)
   TypeId,
   // Memory Layer (v0.5.13+) - GraphDB-Powered Agent Memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.81",
+  "version": "0.6.82",
   "description": "High-performance RDF/SPARQL database with AI agent framework. GraphDB (449ns lookups, 35x faster than RDFox), GraphFrames analytics (PageRank, motifs), Datalog reasoning, HNSW vector embeddings. HyperMindAgent for schema-aware query generation with audit trails. W3C SPARQL 1.1 compliant. Native performance via Rust + NAPI-RS.",
   "main": "index.js",
   "types": "index.d.ts",