@unrdf/knowledge-engine 5.0.1

package/src/lite.mjs

@@ -0,0 +1,222 @@
+/**
+ * @file knowledge-engine/lite.mjs
+ * @description Minimal RDF functionality entry point for bundle size optimization
+ *
+ * This lite bundle exports ONLY the core RDF primitives from n3:
+ * - Store: In-memory quad storage
+ * - Parser: Turtle/N-Triples/N-Quads parsing
+ * - Writer: RDF serialization
+ * - DataFactory: RDF term creation
+ *
+ * EXCLUDES (for 60%+ bundle reduction):
+ * - @comunica/query-sparql (~2.5MB)
+ * - isolated-vm (~5MB native bindings)
+ * - testcontainers (dev-only)
+ * - eyereasoner
+ * - rdf-validate-shacl
+ * - All hook/policy infrastructure
+ *
+ * @example
+ * // Minimal import for basic RDF operations
+ * import { Store, Parser, Writer, DataFactory, parseTurtle, toTurtle } from 'unrdf/knowledge-engine/lite';
+ *
+ * const store = createStore();
+ * const { namedNode, literal, quad } = DataFactory;
+ *
+ * store.addQuad(quad(
+ *   namedNode('http://example.org/alice'),
+ *   namedNode('http://xmlns.com/foaf/0.1/name'),
+ *   literal('Alice')
+ * ));
+ *
+ * @module knowledge-engine/lite
+ * @see {@link https://github.com/rdfjs/N3.js} for N3.js documentation
+ */
+
+/**
+ * JUSTIFIED N3 USAGE (μ(O) Compliance):
+ * This lite.mjs module is a justified boundary for N3 exports because:
+ * 1. It provides streaming parsing with backpressure control (N3.Parser)
+ * 2. It's explicitly designed for lightweight RDF operations without Oxigraph
+ * 3. Users opting into lite.mjs accept N3-based implementation
+ *
+ * For full Oxigraph-based functionality, use the main knowledge-engine exports.
+ */
+
+// Core N3 exports - the essential RDF primitives
+export { Parser, Writer, UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { createStore as _createStore } from '@unrdf/oxigraph'; // Oxigraph Store implementation
+export { _createStore as createStore };
+
+/**
+ * Parse a Turtle string into a Store (lite version - no OTEL tracing)
+ * @param {string} ttl - The Turtle string to parse
+ * @param {string} [baseIRI='http://example.org/'] - Base IRI for resolving relative URIs
+ * @returns {Promise<import('n3').Store>} Promise resolving to a Store containing the parsed quads
+ * @throws {TypeError} If ttl is not a string
+ * @throws {Error} If parsing fails
+ *
+ * @example
+ * const ttl = `
+ *   @prefix ex: <http://example.org/> .
+ *   ex:alice ex:knows ex:bob .
+ * `;
+ * const store = await parseTurtle(ttl);
+ */
+export async function parseTurtle(ttl, baseIRI = 'http://example.org/') {
+  if (typeof ttl !== 'string') {
+    throw new TypeError('parseTurtle: ttl must be a string');
+  }
+  if (typeof baseIRI !== 'string') {
+    throw new TypeError('parseTurtle: baseIRI must be a string');
+  }
+
+  const { Parser } = await import('n3');
+  const parser = new Parser({ baseIRI });
+  const quads = parser.parse(ttl);
+  return _createStore(quads);
+}
+
+/**
+ * Serialize a Store to Turtle format (lite version - no OTEL tracing)
+ * @param {import('n3').Store} store - The store to serialize
+ * @param {Object} [options={}] - Serialization options
+ * @param {Object} [options.prefixes] - Prefix mappings for compact output
+ * @param {string} [options.baseIRI] - Base IRI for the output
+ * @returns {Promise<string>} Promise resolving to the Turtle string
+ * @throws {TypeError} If store is not a valid Store instance
+ * @throws {Error} If serialization fails
+ *
+ * @example
+ * const turtle = await toTurtle(store, {
+ *   prefixes: { ex: 'http://example.org/' }
+ * });
+ */
+export async function toTurtle(store, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('toTurtle: store must be a valid Store instance');
+  }
+
+  const { Writer } = await import('n3');
+  const writer = new Writer({
+    format: 'Turtle',
+    prefixes: options.prefixes || {},
+  });
+
+  const quads = store.getQuads();
+  writer.addQuads(quads);
+
+  return new Promise((resolve, reject) => {
+    writer.end((error, result) => {
+      if (error) {
+        reject(new Error(`Failed to serialize to Turtle: ${error.message}`));
+      } else {
+        if (options.baseIRI) {
+          result = `@base <${options.baseIRI}> .\n\n${result}`;
+        }
+        resolve(result);
+      }
+    });
+  });
+}
+
+/**
+ * Serialize a Store to N-Quads format (lite version - no OTEL tracing)
+ * @param {import('n3').Store} store - The store to serialize
+ * @param {Object} [options={}] - Serialization options
+ * @returns {Promise<string>} Promise resolving to the N-Quads string
+ * @throws {TypeError} If store is not a valid Store instance
+ * @throws {Error} If serialization fails
+ *
+ * @example
+ * const nquads = await toNQuads(store);
+ */
+export async function toNQuads(store, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('toNQuads: store must be a valid Store instance');
+  }
+
+  const { Writer } = await import('n3');
+  const writer = new Writer({
+    format: 'N-Quads',
+    ...options,
+  });
+
+  const quads = store.getQuads();
+  writer.addQuads(quads);
+
+  return new Promise((resolve, reject) => {
+    writer.end((error, result) => {
+      if (error) {
+        reject(new Error(`Failed to serialize to N-Quads: ${error.message}`));
+      } else {
+        resolve(result);
+      }
+    });
+  });
+}
+
+/**
+ * Create a quad using DataFactory (convenience function)
+ * @param {string} subject - Subject IRI
+ * @param {string} predicate - Predicate IRI
+ * @param {string|{value: string, language?: string, datatype?: string}} object - Object value
+ * @param {string} [graph] - Optional graph IRI
+ * @returns {import('n3').Quad} The created quad
+ *
+ * @example
+ * const q = createQuad(
+ *   'http://example.org/alice',
+ *   'http://xmlns.com/foaf/0.1/name',
+ *   { value: 'Alice', language: 'en' }
+ * );
+ */
+export function createQuad(subject, predicate, object, graph) {
+  const { DataFactory } = require('n3');
+  const { namedNode, literal, quad, defaultGraph } = DataFactory;
+
+  const subjectNode = namedNode(subject);
+  const predicateNode = namedNode(predicate);
+
+  let objectNode;
+  if (typeof object === 'string') {
+    // Check if it looks like a URI
+    if (
+      object.startsWith('http://') ||
+      object.startsWith('https://') ||
+      object.startsWith('urn:')
+    ) {
+      objectNode = namedNode(object);
+    } else {
+      objectNode = literal(object);
+    }
+  } else if (typeof object === 'object') {
+    if (object.language) {
+      objectNode = literal(object.value, object.language);
+    } else if (object.datatype) {
+      objectNode = literal(object.value, namedNode(object.datatype));
+    } else {
+      objectNode = literal(object.value);
+    }
+  }
+
+  const graphNode = graph ? namedNode(graph) : defaultGraph();
+  return quad(subjectNode, predicateNode, objectNode, graphNode);
+}
+
+/**
+ * Bundle size comparison (approximate):
+ *
+ * Full knowledge-engine: ~8-10MB
+ * - @comunica/query-sparql: ~2.5MB
+ * - isolated-vm: ~5MB (native)
+ * - eyereasoner: ~500KB
+ * - rdf-validate-shacl: ~200KB
+ * - n3: ~150KB
+ * - hooks/policy: ~100KB
+ *
+ * Lite knowledge-engine: ~150KB
+ * - n3 only: ~150KB
+ *
+ * Savings: ~98% for basic RDF operations
+ */

package/src/lockchain-writer-browser.mjs

@@ -0,0 +1,414 @@
+/**
+ * @file Browser-compatible Lockchain Writer
+ * @module lockchain-writer-browser
+ *
+ * @description
+ * Browser-compatible version of the lockchain writer that stores entries in memory
+ * or browser storage instead of Git commits. Provides cryptographic integrity
+ * verification without Git dependencies.
+ */
+
+import { randomUUID, createHash, _fs } from './browser-shims.mjs';
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { _blake3 } from '@noble/hashes/blake3.js';
+import { utf8ToBytes, bytesToHex } from '@noble/hashes/utils.js';
+import { z } from 'zod';
+
+/**
+ * Schema for lockchain entry
+ */
+const LockchainEntrySchema = z.object({
+  id: z.string().uuid(),
+  timestamp: z.number(),
+  receipt: z.any(), // Transaction receipt
+  signature: z.object({
+    algorithm: z.string(),
+    value: z.string(),
+    publicKey: z.string().optional(),
+  }),
+  previousHash: z.string().optional().nullable(),
+  merkleRoot: z.string().optional(),
+  storageKey: z.string().optional(), // Browser storage key instead of git commit
+  storageRef: z.string().optional(),
+});
+
+/**
+ * Schema for lockchain configuration
+ */
+const LockchainConfigSchema = z.object({
+  storageType: z.enum(['memory', 'localStorage', 'sessionStorage', 'indexedDB']).default('memory'),
+  algorithm: z.enum(['sha256', 'sha3-256', 'blake3']).default('sha3-256'),
+  batchSize: z.number().int().positive().default(10),
+  enableMerkle: z.boolean().default(true),
+  enablePersistence: z.boolean().default(true),
+  storagePrefix: z.string().default('lockchain'),
+  maxAgeMs: z.number().int().positive().optional(), // Time to live
+});
+
+/**
+ * Browser-compatible Lockchain Writer
+ */
+export class BrowserLockchainWriter {
+  /**
+   *
+   */
+  constructor(config = {}) {
+    const validatedConfig = LockchainConfigSchema.parse({
+      ...config,
+      // Override Git-specific options for browser
+      enableGitAnchoring: false,
+      gitRepo: undefined,
+    });
+    this.config = validatedConfig;
+
+    // Initialize storage
+    this.entries = [];
+    this.lastHash = null;
+    this.processingBatches = new Set();
+
+    // Browser storage API
+    this.storage = this._initStorage();
+
+    // Load existing entries
+    this._loadEntries().catch(err => {
+      console.warn('Failed to load entries during initialization:', err.message);
+    });
+  }
+
+  /**
+   * Initialize browser storage according to config
+   * @private
+   */
+  _initStorage() {
+    switch (this.config.storageType) {
+      case 'localStorage':
+        return {
+          get: key => globalThis?.localStorage?.getItem(`${this.config.storagePrefix}_${key}`),
+          set: (key, value) =>
+            globalThis?.localStorage?.setItem(`${this.config.storagePrefix}_${key}`, value),
+          remove: key =>
+            globalThis?.localStorage?.removeItem(`${this.config.storagePrefix}_${key}`),
+        };
+      case 'sessionStorage':
+        return {
+          get: key => globalThis?.sessionStorage?.getItem(`${this.config.storagePrefix}_${key}`),
+          set: (key, value) =>
+            globalThis?.sessionStorage?.setItem(`${this.config.storagePrefix}_${key}`, value),
+          remove: key =>
+            globalThis?.sessionStorage?.removeItem(`${this.config.storagePrefix}_${key}`),
+        };
+      case 'indexedDB':
+        // Simplified IndexedDB implementation would go here
+        console.warn('IndexedDB storage not yet implemented, falling back to memory');
+        return this._initMemoryStorage();
+      default:
+        return this._initMemoryStorage();
+    }
+  }
+
+  /**
+   * Initialize memory-based storage
+   * @private
+   */
+  _initMemoryStorage() {
+    const memoryStorage = new Map();
+    return {
+      get: key => memoryStorage.get(key),
+      set: (key, value) => memoryStorage.set(key, value),
+      remove: key => memoryStorage.delete(key),
+    };
+  }
+
+  /**
+   * Load existing entries from storage
+   * @private
+   */
+  async _loadEntries() {
+    try {
+      const entriesKey = `${this.config.storagePrefix}_entries`;
+      const entriesData = this.storage.get(entriesKey);
+
+      if (entriesData) {
+        this.entries = JSON.parse(entriesData);
+
+        // Restore last hash
+        const lastEntry = this.entries[this.entries.length - 1];
+        if (lastEntry) {
+          this.lastHash = await this._calculateEntryHash(lastEntry);
+        }
+      }
+    } catch (error) {
+      console.warn('Failed to load existing entries:', error.message);
+      this.entries = [];
+      this.lastHash = null;
+    }
+  }
+
+  /**
+   * Save entries to storage
+   * @private
+   */
+  async _saveEntries() {
+    try {
+      const entriesKey = `${this.config.storagePrefix}_entries`;
+      this.storage.set(entriesKey, JSON.stringify(this.entries));
+    } catch (error) {
+      console.warn('Failed to save entries:', error.message);
+    }
+  }
+
+  /**
+   * Write a receipt to the lockchain
+   * @param {Object} receipt - Transaction receipt
+   * @param {Object} [options] - Write options
+   * @returns {Promise<Object>} Lockchain entry
+   */
+  async writeReceipt(receipt, options = {}) {
+    const entryId = randomUUID();
+    const timestamp = Date.now();
+
+    // Create lockchain entry
+    const entry = {
+      id: entryId,
+      timestamp,
+      receipt: this._serializeReceipt(receipt),
+      signature: await this._signEntry(receipt, entryId, timestamp),
+      previousHash: this.lastHash || null,
+      merkleRoot: options.merkleRoot,
+    };
+
+    // Validate entry
+    const validatedEntry = LockchainEntrySchema.parse(entry);
+
+    // Store entry
+    await this._storeEntry(validatedEntry);
+
+    // Update hash chain
+    this.lastHash = await this._calculateEntryHash(validatedEntry);
+
+    // Persist to storage
+    await this._saveEntries();
+
+    return validatedEntry;
+  }
+
+  /**
+   * Write multiple receipts in a batch
+   * @param {Array} receipts - Array of transaction receipts
+   * @param {Object} [options] - Batch options
+   * @returns {Promise<Array>} Array of lockchain entries
+   */
+  async writeReceiptBatch(receipts, _options = {}) {
+    const batchId = `batch_${randomUUID().slice(0, 8)}`;
+    const validatedReceipts = receipts.map(r => (typeof r === 'string' ? JSON.parse(r) : r));
+
+    const batchPromise = this._processBatch(validatedReceipts, batchId);
+    this.processingBatches.add(batchId);
+
+    try {
+      const entries = await batchPromise;
+      this.processingBatches.delete(batchId);
+      return entries;
+    } catch (error) {
+      this.processingBatches.delete(batchId);
+      throw error;
+    }
+  }
+
+  /**
+   * Process a batch of receipts
+   * @private
+   */
+  async _processBatch(receipts, batchId) {
+    const entries = [];
+    const merkleRoot = this.config.enableMerkle ? await this._calculateMerkleRoot(receipts) : null;
+
+    for (let i = 0; i < receipts.length; i++) {
+      const receipt = receipts[i];
+      const entry = await this.writeReceipt(receipt, {
+        batchId,
+        batchIndex: i,
+        merkleRoot,
+      });
+      entries.push(entry);
+    }
+
+    return entries;
+  }
+
+  /**
+   * Calculate Merkle root from receipts
+   * @private
+   */
+  async _calculateMerkleRoot(receipts) {
+    const hashes = await Promise.all(
+      receipts.map(async receipt => {
+        const serialized = this._serializeReceipt(receipt);
+        return bytesToHex(sha3_256(utf8ToBytes(JSON.stringify(serialized))));
+      })
+    );
+
+    // Simple binary tree merkle calculation
+    let current = hashes;
+    while (current.length > 1) {
+      const next = [];
+      for (let i = 0; i < current.length; i += 2) {
+        const left = current[i];
+        const right = current[i + 1] || current[i]; // Pad with self if odd
+        const combined = left + right;
+        next.push(bytesToHex(sha3_256(utf8ToBytes(combined))));
+      }
+      current = next;
+    }
+
+    return current[0];
+  }
+
+  /**
+   * Store a single entry
+   * @private
+   */
+  async _storeEntry(entry) {
+    // Store individual entry
+    const storageKey = `entry_${entry.id}`;
+    this.storage.set(storageKey, JSON.stringify(entry));
+
+    // Update entries array
+    this.entries.push({
+      ...entry,
+      storageKey,
+    });
+  }
+
+  /**
+   * Serialize receipt for storage
+   * @private
+   */
+  _serializeReceipt(receipt) {
+    if (typeof receipt === 'string') {
+      return JSON.parse(receipt);
+    }
+    return receipt;
+  }
+
+  /**
+   * Sign an entry
+   * @private
+   */
+  async _signEntry(receipt, entryId, timestamp) {
+    const hash = createHash(this.config.algorithm);
+    const signature = hash.update(
+      JSON.stringify({
+        receipt,
+        entryId,
+        timestamp,
+        previousHash: this.lastHash,
+      })
+    );
+
+    return {
+      algorithm: this.config.algorithm,
+      value: await signature.digest('hex'),
+    };
+  }
+
+  /**
+   * Calculate hash for an entry
+   * @private
+   */
+  async _calculateEntryHash(entry) {
+    const hash = createHash(this.config.algorithm);
+    return await hash.update(JSON.stringify(entry)).digest('hex');
+  }
+
+  /**
+   * Verify lockchain integrity
+   * @returns {Promise<Object>} Verification result
+   */
+  async verifyIntegrity() {
+    const results = [];
+    let previousHash = null;
+
+    for (let i = 0; i < this.entries.length; i++) {
+      const entry = this.entries[i];
+      const expectedHash = await this._calculateEntryHash(entry);
+
+      const isValid =
+        expectedHash === entry.previousHash &&
+        (previousHash === null || entry.previousHash === previousHash);
+
+      results.push({
+        index: i,
+        entryId: entry.id,
+        valid: isValid,
+        hash: expectedHash,
+      });
+
+      if (!isValid) {
+        break; // Chain is broken
+      }
+
+      previousHash = expectedHash;
+    }
+
+    const isValid = results.every(r => r.valid);
+
+    return {
+      valid: isValid,
+      totalEntries: this.entries.length,
+      results,
+      verificationTimestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Get lockchain statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    return {
+      totalEntries: this.entries.length,
+      processingBatches: this.processingBatches.size,
+      config: this.config,
+      lastHash: this.lastHash,
+      storageType: this.config.storageType,
+      oldestEntry: this.entries.length > 0 ? this.entries[0].timestamp : null,
+      newestEntry: this.entries.length > 0 ? this.entries[this.entries.length - 1].timestamp : null,
+    };
+  }
+
+  /**
+   * Clear all entries (use with caution)
+   */
+  async clear() {
+    this.entries = [];
+    this.lastHash = null;
+    this.processingBatches.clear();
+
+    if (this.config.enablePersistence) {
+      // Clear persisted entries
+      this.entries.forEach(entry => {
+        if (entry.storageKey) {
+          this.storage.remove(entry.storageKey);
+        }
+      });
+
+      const entriesKey = `${this.config.storagePrefix}_entries`;
+      this.storage.remove(entriesKey);
+    }
+  }
+}
+
+/**
+ * Create a browser-compatible lockchain writer
+ * @param {Object} [config] - Lockchain configuration
+ * @returns {BrowserLockchainWriter} New writer instance
+ */
+export function createBrowserLockchainWriter(config = {}) {
+  return new BrowserLockchainWriter(config);
+}
+
+// Export for compatibility
+export { BrowserLockchainWriter as LockchainWriter };
+
+export default BrowserLockchainWriter;