@unrdf/kgc-substrate 26.4.2

package/src/KnowledgeStore.mjs

@@ -0,0 +1,325 @@
+/**
+ * KnowledgeStore - Deterministic, Hash-Stable, Immutable Append-Only Log
+ *
+ * Core substrate for KGC multi-agent system. Provides:
+ * - Immutable append-only log of indexed triples
+ * - Deterministic snapshot generation with BLAKE3 hashing
+ * - Hash-stable canonicalization (lexicographic quad ordering)
+ * - Query interface: selectTriples(pattern) → Set<Quad>
+ * - State commitment: hash(store_state) → stable digest
+ *
+ * TRANCHE ISOLATION: Only depends on @unrdf/kgc-4d, @unrdf/oxigraph, @unrdf/core
+ * NO dependencies on other tranches.
+ */
+
+import { KGCStore, freezeUniverse, GitBackbone } from '@unrdf/kgc-4d';
+import { dataFactory } from '@unrdf/oxigraph';
+import { blake3 } from 'hash-wasm';
+import {
+  validateStorageSnapshot,
+  validateQueryPattern,
+  validateStateCommitment
+} from './types.mjs';
+
+/**
+ * KnowledgeStore - Wraps KGCStore with deterministic, hash-stable interface
+ *
+ * @example
+ * import { KnowledgeStore } from '@unrdf/kgc-substrate';
+ * const store = new KnowledgeStore({ nodeId: 'agent-1' });
+ * const { index } = await store.appendTriple('add', subject, predicate, object);
+ * const snapshot = await store.generateSnapshot();
+ * console.assert(snapshot.quads_hash, 'Snapshot has deterministic hash');
+ */
+export class KnowledgeStore {
+  /**
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.nodeId] - Node ID for vector clock (defaults to random)
+   * @param {string} [options.gitDir] - Git directory for snapshot storage (defaults to '.kgc-substrate-git')
+   */
+  constructor(options = {}) {
+    // Validate inputs
+    if (options !== null && typeof options !== 'object') {
+      throw new TypeError('KnowledgeStore: options must be an object');
+    }
+
+    this.nodeId = options.nodeId || this._generateNodeId();
+    this.gitDir = options.gitDir || '.kgc-substrate-git';
+
+    // Initialize KGCStore (4D event logging backend)
+    this.store = new KGCStore({ nodeId: this.nodeId });
+
+    // Initialize GitBackbone (snapshot storage)
+    this.git = new GitBackbone(this.gitDir);
+
+    // Append-only log index (BigInt for overflow protection)
+    this.logIndex = 0n;
+
+    // Epoch counter for snapshots
+    this.epoch = 0;
+  }
+
+  /**
+   * Generate unique node ID
+   *
+   * @returns {string} Node ID with 'ks-' prefix
+   * @private
+   */
+  _generateNodeId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return `ks-${crypto.randomUUID().slice(0, 8)}`;
+    }
+    try {
+      const crypto = require('crypto');
+      return `ks-${crypto.randomUUID().slice(0, 8)}`;
+    } catch {
+      return `ks-${Date.now().toString(36)}`;
+    }
+  }
+
+  /**
+   * Append triple to immutable log
+   *
+   * Enforces append-only property: triples are never modified, only added or marked deleted.
+   * Each operation gets a sequential index for deterministic replay.
+   *
+   * @param {'add'|'delete'} operation - Operation type
+   * @param {Object} subject - RDF subject term
+   * @param {Object} predicate - RDF predicate term
+   * @param {Object} object - RDF object term
+   * @param {Object} [graph] - RDF graph term (defaults to Universe graph)
+   * @returns {Promise<{index: bigint, timestamp_ns: bigint}>} Log entry metadata
+   * @throws {TypeError} If parameters are invalid
+   * @throws {Error} If append operation fails
+   *
+   * @example
+   * const s = dataFactory.namedNode('http://ex.org/s');
+   * const p = dataFactory.namedNode('http://ex.org/p');
+   * const o = dataFactory.literal('value');
+   * const { index } = await store.appendTriple('add', s, p, o);
+   * console.assert(typeof index === 'bigint', 'Returns BigInt index');
+   */
+  async appendTriple(operation, subject, predicate, object, graph = null) {
+    // Input validation
+    if (operation !== 'add' && operation !== 'delete') {
+      throw new TypeError(`appendTriple: operation must be 'add' or 'delete', got '${operation}'`);
+    }
+    if (!subject || typeof subject.value !== 'string') {
+      throw new TypeError('appendTriple: subject must be a valid RDF term');
+    }
+    if (!predicate || typeof predicate.value !== 'string') {
+      throw new TypeError('appendTriple: predicate must be a valid RDF term');
+    }
+    if (!object || typeof object.value !== 'string') {
+      throw new TypeError('appendTriple: object must be a valid RDF term');
+    }
+
+    try {
+      // Create delta for KGCStore
+      const delta = {
+        type: operation,
+        subject,
+        predicate,
+        object,
+      };
+
+      // Append to KGCStore event log
+      const { receipt } = await this.store.appendEvent(
+        {
+          type: operation === 'add' ? 'CREATE' : 'DELETE',
+          payload: {
+            operation,
+            log_index: this.logIndex.toString(),
+          },
+        },
+        [delta]
+      );
+
+      // Increment log index (immutable sequence)
+      const currentIndex = this.logIndex;
+      this.logIndex++;
+
+      return {
+        index: currentIndex,
+        timestamp_ns: BigInt(receipt.t_ns),
+      };
+    } catch (error) {
+      throw new Error(`appendTriple failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Select triples matching a pattern (supports wildcards)
+   *
+   * @param {Object} pattern - Query pattern with subject, predicate, object, graph
+   * @param {Object|null} pattern.subject - Subject or null for wildcard
+   * @param {Object|null} pattern.predicate - Predicate or null for wildcard
+   * @param {Object|null} pattern.object - Object or null for wildcard
+   * @param {Object|null} [pattern.graph] - Graph or null for wildcard
+   * @returns {Set<Object>} Set of matching quads
+   * @throws {Error} If pattern is invalid
+   *
+   * @example
+   * const results = store.selectTriples({ subject: s, predicate: null, object: null });
+   * console.log('Matching triples:', results.size);
+   */
+  selectTriples(pattern) {
+    try {
+      // Validate pattern
+      validateQueryPattern(pattern);
+
+      // Query KGCStore using match()
+      const matches = this.store.match(
+        pattern.subject,
+        pattern.predicate,
+        pattern.object,
+        pattern.graph || null
+      );
+
+      return new Set([...matches]);
+    } catch (error) {
+      throw new Error(`selectTriples failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Generate deterministic snapshot with hash-stable canonicalization
+   *
+   * Steps:
+   * 1. Extract all quads from Universe graph
+   * 2. Sort lexicographically (S-P-O) for canonical ordering
+   * 3. Serialize to N-Quads format
+   * 4. Hash with BLAKE3 (deterministic)
+   * 5. Commit to Git for immutable storage
+   * 6. Return snapshot metadata
+   *
+   * @returns {Promise<Object>} StorageSnapshot with epoch, timestamp_ns, quads_hash, commit_hash, snapshot_id
+   * @throws {Error} If snapshot generation fails
+   *
+   * @example
+   * const snapshot = await store.generateSnapshot();
+   * console.assert(snapshot.quads_hash, 'Has deterministic hash');
+   * console.assert(snapshot.snapshot_id, 'Has UUID');
+   */
+  async generateSnapshot() {
+    try {
+      // Freeze universe using KGC-4D
+      const freezeReceipt = await freezeUniverse(this.store, this.git);
+
+      // Create snapshot metadata
+      const snapshot = {
+        epoch: this.epoch,
+        timestamp_ns: BigInt(freezeReceipt.t_ns),
+        quads_hash: freezeReceipt.universe_hash,
+        commit_hash: freezeReceipt.git_ref,
+        snapshot_id: freezeReceipt.id,
+        quad_count: await this.getQuadCount(),
+      };
+
+      // Validate snapshot schema
+      validateStorageSnapshot(snapshot);
+
+      // Increment epoch
+      this.epoch++;
+
+      return snapshot;
+    } catch (error) {
+      throw new Error(`generateSnapshot failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get current state commitment (hash of store state)
+   *
+   * Provides cryptographic commitment to current state without full snapshot.
+   * Useful for lightweight verification.
+   *
+   * @returns {Promise<Object>} StateCommitment with state_hash, log_index, timestamp_ns, quad_count
+   * @throws {Error} If commitment generation fails
+   *
+   * @example
+   * const commitment = await store.getStateCommitment();
+   * console.assert(commitment.state_hash, 'Has state hash');
+   */
+  async getStateCommitment() {
+    try {
+      // Get all quads from Universe graph
+      const universeGraph = dataFactory.namedNode('http://kgc.io/graph/universe');
+      const quads = [...this.store.match(null, null, null, universeGraph)];
+
+      // Sort for canonical ordering
+      quads.sort((a, b) => {
+        const sCompare = a.subject.value < b.subject.value ? -1 :
+                         a.subject.value > b.subject.value ? 1 : 0;
+        if (sCompare !== 0) return sCompare;
+
+        const pCompare = a.predicate.value < b.predicate.value ? -1 :
+                         a.predicate.value > b.predicate.value ? 1 : 0;
+        if (pCompare !== 0) return pCompare;
+
+        return a.object.value < b.object.value ? -1 :
+               a.object.value > b.object.value ? 1 : 0;
+      });
+
+      // Serialize to canonical string
+      const canonicalString = quads.map(q =>
+        `${q.subject.value}|${q.predicate.value}|${q.object.value}`
+      ).join('\n');
+
+      // Hash with BLAKE3
+      const stateHash = await blake3(canonicalString);
+
+      const commitment = {
+        state_hash: stateHash,
+        log_index: this.logIndex,
+        timestamp_ns: BigInt(Date.now()) * 1_000_000n, // Convert ms to ns
+        quad_count: quads.length,
+      };
+
+      // Validate commitment schema
+      validateStateCommitment(commitment);
+
+      return commitment;
+    } catch (error) {
+      throw new Error(`getStateCommitment failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get current quad count
+   *
+   * @returns {Promise<number>} Total number of quads in Universe graph
+   */
+  async getQuadCount() {
+    const universeGraph = dataFactory.namedNode('http://kgc.io/graph/universe');
+    const quads = [...this.store.match(null, null, null, universeGraph)];
+    return quads.length;
+  }
+
+  /**
+   * Get current log index
+   *
+   * @returns {bigint} Current append-only log index
+   */
+  getLogIndex() {
+    return this.logIndex;
+  }
+
+  /**
+   * Get current epoch
+   *
+   * @returns {number} Current snapshot epoch
+   */
+  getEpoch() {
+    return this.epoch;
+  }
+
+  /**
+   * Get node ID
+   *
+   * @returns {string} Node ID for this store instance
+   */
+  getNodeId() {
+    return this.nodeId;
+  }
+}

package/src/ReceiptChain.mjs

@@ -0,0 +1,292 @@
+/**
+ * ReceiptChain - Immutable ledger with merkle tree chaining
+ *
+ * Provides cryptographically-verifiable chain of receipts where each block
+ * commits to the previous block via hash chaining, creating an immutable audit trail.
+ *
+ * Block structure:
+ * - before_hash: Hash of previous block (merkle root)
+ * - after_hash: Hash of current block content
+ * - timestamp_ns: UTC nanoseconds (monotonic)
+ * - agent_id: Agent identifier
+ * - toolchain_version: Toolchain version string
+ * - artifacts: Array of artifact objects
+ *
+ * @module ReceiptChain
+ */
+
+import { sha256 } from 'hash-wasm';
+import { z } from 'zod';
+
+/**
+ * Artifact schema - individual work products in a block
+ */
+const ArtifactSchema = z.object({
+  type: z.string(),
+  path: z.string(),
+  hash: z.string(),
+  size_bytes: z.number().int().nonnegative()
+});
+
+/**
+ * Block schema - immutable ledger entry
+ */
+const BlockSchema = z.object({
+  before_hash: z.string().length(64), // SHA256 hex
+  after_hash: z.string().length(64),  // SHA256 hex
+  timestamp_ns: z.bigint(),
+  agent_id: z.string().min(1),
+  toolchain_version: z.string().min(1),
+  artifacts: z.array(ArtifactSchema)
+});
+
+/**
+ * Receipt chain configuration schema
+ */
+const ConfigSchema = z.object({
+  genesis_hash: z.string().length(64).optional(),
+  enforce_monotonic_time: z.boolean().default(true)
+});
+
+/**
+ * ReceiptChain class - Immutable ledger with merkle tree chaining
+ */
+export class ReceiptChain {
+  /**
+   * Genesis block hash - conventionally all zeros
+   * @type {string}
+   */
+  static GENESIS_HASH = '0'.repeat(64);
+
+  /**
+   * Create a new receipt chain
+   * @param {Object} config - Configuration options
+   * @param {string} [config.genesis_hash] - Custom genesis hash (default: all zeros)
+   * @param {boolean} [config.enforce_monotonic_time=true] - Enforce monotonic timestamps
+   */
+  constructor(config = {}) {
+    const validated = ConfigSchema.parse(config);
+    this.blocks = [];
+    this.genesis_hash = validated.genesis_hash || ReceiptChain.GENESIS_HASH;
+    this.enforce_monotonic_time = validated.enforce_monotonic_time;
+    this.last_timestamp_ns = 0n;
+  }
+
+  /**
+   * Get current chain head hash
+   * @returns {string} Hash of the last block, or genesis hash if empty
+   */
+  getHeadHash() {
+    if (this.blocks.length === 0) {
+      return this.genesis_hash;
+    }
+    return this.blocks[this.blocks.length - 1].after_hash;
+  }
+
+  /**
+   * Get chain length
+   * @returns {number} Number of blocks in the chain
+   */
+  getLength() {
+    return this.blocks.length;
+  }
+
+  /**
+   * Get block by index
+   * @param {number} index - Block index (0-based)
+   * @returns {Object|null} Block or null if out of bounds
+   */
+  getBlock(index) {
+    if (index < 0 || index >= this.blocks.length) {
+      return null;
+    }
+    return this.blocks[index];
+  }
+
+  /**
+   * Get all blocks (defensive copy to prevent mutation)
+   * @returns {Array<Object>} Array of all blocks
+   */
+  getAllBlocks() {
+    return structuredClone(this.blocks);
+  }
+
+  /**
+   * Compute hash of block content (before appending to chain)
+   * Hash includes: timestamp, agent_id, toolchain_version, artifacts
+   * Does NOT include before_hash/after_hash (those are chain metadata)
+   *
+   * @param {Object} content - Block content to hash
+   * @param {bigint} content.timestamp_ns - UTC nanoseconds
+   * @param {string} content.agent_id - Agent identifier
+   * @param {string} content.toolchain_version - Toolchain version
+   * @param {Array<Object>} content.artifacts - Array of artifacts
+   * @returns {Promise<string>} SHA256 hex digest
+   * @private
+   */
+  async _computeContentHash(content) {
+    // Canonical JSON serialization for deterministic hashing
+    const canonical = JSON.stringify({
+      timestamp_ns: content.timestamp_ns.toString(),
+      agent_id: content.agent_id,
+      toolchain_version: content.toolchain_version,
+      artifacts: content.artifacts
+    });
+    return await sha256(canonical);
+  }
+
+  /**
+   * Compute merkle root of current block + previous hash
+   * Merkle root = SHA256(before_hash || after_hash)
+   *
+   * @param {string} before_hash - Hash of previous block
+   * @param {string} after_hash - Hash of current block content
+   * @returns {Promise<string>} Merkle root hash
+   * @private
+   */
+  async _computeMerkleRoot(before_hash, after_hash) {
+    return await sha256(before_hash + after_hash);
+  }
+
+  /**
+   * Append a new block to the chain (immutable operation)
+   *
+   * @param {Object} blockData - Block data to append
+   * @param {string} blockData.agent_id - Agent identifier
+   * @param {string} blockData.toolchain_version - Toolchain version
+   * @param {Array<Object>} blockData.artifacts - Array of artifacts
+   * @param {bigint} [blockData.timestamp_ns] - Custom timestamp (default: now)
+   * @returns {Promise<Object>} Appended block with receipt
+   * @throws {Error} If validation fails or timestamp not monotonic
+   *
+   * @example
+   * const chain = new ReceiptChain();
+   * const block = await chain.append({
+   *   agent_id: 'agent-2',
+   *   toolchain_version: '1.0.0',
+   *   artifacts: [{ type: 'code', path: 'foo.mjs', hash: 'abc123', size_bytes: 1024 }]
+   * });
+   */
+  async append(blockData) {
+    // Validate input structure
+    const { agent_id, toolchain_version, artifacts, timestamp_ns } = blockData;
+
+    if (!agent_id || typeof agent_id !== 'string') {
+      throw new Error('ReceiptChain.append: agent_id is required and must be a string');
+    }
+    if (!toolchain_version || typeof toolchain_version !== 'string') {
+      throw new Error('ReceiptChain.append: toolchain_version is required and must be a string');
+    }
+    if (!Array.isArray(artifacts)) {
+      throw new Error('ReceiptChain.append: artifacts must be an array');
+    }
+
+    // Validate artifacts
+    artifacts.forEach((artifact, idx) => {
+      try {
+        ArtifactSchema.parse(artifact);
+      } catch (err) {
+        throw new Error(`ReceiptChain.append: Invalid artifact at index ${idx}: ${err.message}`);
+      }
+    });
+
+    // Get timestamp (custom or now)
+    const timestamp = timestamp_ns || BigInt(Date.now()) * 1_000_000n;
+
+    // Enforce monotonic time if enabled
+    if (this.enforce_monotonic_time && timestamp <= this.last_timestamp_ns) {
+      throw new Error(
+        `ReceiptChain.append: Timestamp not monotonic (${timestamp} <= ${this.last_timestamp_ns})`
+      );
+    }
+
+    // Get previous block hash (genesis or last block)
+    const before_hash = this.getHeadHash();
+
+    // Compute content hash
+    const content = { timestamp_ns: timestamp, agent_id, toolchain_version, artifacts };
+    const after_hash = await this._computeContentHash(content);
+
+    // Create block
+    const block = {
+      before_hash,
+      after_hash,
+      timestamp_ns: timestamp,
+      agent_id,
+      toolchain_version,
+      artifacts
+    };
+
+    // Validate block schema
+    BlockSchema.parse(block);
+
+    // Append to chain (immutable - no mutation of existing blocks)
+    this.blocks.push(Object.freeze(block));
+    this.last_timestamp_ns = timestamp;
+
+    return {
+      block,
+      index: this.blocks.length - 1,
+      merkle_root: await this._computeMerkleRoot(before_hash, after_hash)
+    };
+  }
+
+  /**
+   * Serialize chain to JSON
+   * @returns {Object} Serialized chain
+   */
+  toJSON() {
+    return {
+      genesis_hash: this.genesis_hash,
+      length: this.blocks.length,
+      head_hash: this.getHeadHash(),
+      blocks: this.blocks.map(block => ({
+        ...block,
+        timestamp_ns: block.timestamp_ns.toString() // BigInt to string
+      }))
+    };
+  }
+
+  /**
+   * Deserialize chain from JSON
+   * @param {Object} json - Serialized chain
+   * @returns {ReceiptChain} Reconstructed chain
+   */
+  static fromJSON(json) {
+    const chain = new ReceiptChain({
+      genesis_hash: json.genesis_hash,
+      enforce_monotonic_time: false // Don't enforce when loading
+    });
+
+    // Restore blocks
+    for (const blockData of json.blocks) {
+      const block = {
+        ...blockData,
+        timestamp_ns: BigInt(blockData.timestamp_ns)
+      };
+      chain.blocks.push(Object.freeze(block));
+      chain.last_timestamp_ns = block.timestamp_ns;
+    }
+
+    return chain;
+  }
+
+  /**
+   * Encode chain to base64 (for embedding in receipts)
+   * @returns {string} Base64-encoded JSON
+   */
+  toBase64() {
+    const json = JSON.stringify(this.toJSON());
+    return Buffer.from(json, 'utf8').toString('base64');
+  }
+
+  /**
+   * Decode chain from base64
+   * @param {string} base64 - Base64-encoded chain
+   * @returns {ReceiptChain} Reconstructed chain
+   */
+  static fromBase64(base64) {
+    const json = JSON.parse(Buffer.from(base64, 'base64').toString('utf8'));
+    return ReceiptChain.fromJSON(json);
+  }
+}