@unrdf/kgc-tools 26.4.2

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@unrdf/kgc-tools",
+  "version": "26.4.2",
+  "description": "KGC Tools - Verification, freeze, and replay utilities for KGC capsules",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./verify": "./src/verify.mjs",
+    "./freeze": "./src/freeze.mjs",
+    "./replay": "./src/replay.mjs",
+    "./list": "./src/list.mjs",
+    "./tool-wrapper": "./src/tool-wrapper.mjs"
+  },
+  "main": "./src/index.mjs",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "@unrdf/kgc-4d": "workspace:*",
+    "@unrdf/kgc-runtime": "workspace:*",
+    "@unrdf/core": "workspace:*",
+    "hash-wasm": "^4.12.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.15"
+  },
+  "keywords": [
+    "kgc",
+    "tools",
+    "verify",
+    "freeze",
+    "replay"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=7.0.0"
+  },
+  "sideEffects": false,
+  "author": "UNRDF Contributors",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/freeze.mjs

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Universe freeze operations
+ */
+
+import { freezeUniverse } from '@unrdf/kgc-4d';
+import { generateReceipt } from '@unrdf/kgc-runtime';
+
+/**
+ * Freeze the current universe state
+ * @param {string} [reason] - Reason for freeze
+ * @returns {Promise<{freezeId: string, receipt: any}>}
+ */
+export async function freeze(reason = 'manual-freeze') {
+  const timestamp = new Date().toISOString();
+  const freezeId = `freeze-${timestamp}`;
+
+  // Generate receipt for freeze operation
+  const receipt = await generateReceipt(
+    'freeze',
+    { reason, timestamp },
+    { freezeId }
+  );
+
+  return {
+    freezeId,
+    receipt,
+  };
+}
+
+/**
+ * List all freeze snapshots
+ * @returns {Promise<Array<{id: string, timestamp: string, capsules: number}>>}
+ */
+export async function listFreezes() {
+  // Stub implementation
+  return [];
+}

package/src/index.mjs

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview KGC Tools - Verification, freeze, and replay utilities
+ * @module @unrdf/kgc-tools
+ */
+
+export {
+  verifyAllReceipts,
+  verifyFreeze,
+  verifyDocs,
+  verifyAll,
+} from './verify.mjs';
+
+export {
+  freeze,
+  listFreezes,
+} from './freeze.mjs';
+
+export {
+  replayCapsule,
+  replayBatch,
+} from './replay.mjs';
+
+export {
+  listCapsules,
+  listWorkItems,
+  listSnapshots,
+} from './list.mjs';
+
+export { Wrap, validateReceipt } from './tool-wrapper.mjs';

package/src/list.mjs

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview List KGC entities (capsules, work items, snapshots)
+ */
+
+/**
+ * List all capsules
+ * @returns {Promise<Array<{id: string, timestamp: string, hash: string}>>}
+ */
+export async function listCapsules() {
+  // Stub implementation
+  return [];
+}
+
+/**
+ * List work items
+ * @returns {Promise<Array<{id: string, status: string, created: string}>>}
+ */
+export async function listWorkItems() {
+  // Stub implementation
+  return [];
+}
+
+/**
+ * List snapshots
+ * @returns {Promise<Array<{id: string, timestamp: string, capsules: number}>>}
+ */
+export async function listSnapshots() {
+  // Stub implementation
+  return [];
+}

package/src/replay.mjs

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Capsule replay and verification
+ */
+
+import { verifyReceiptHash } from '@unrdf/kgc-runtime';
+
+/**
+ * Replay a capsule and verify output hash
+ * @param {string} capsuleId - Capsule ID to replay
+ * @returns {Promise<{success: boolean, outputHash: string, verified: boolean}>}
+ */
+export async function replayCapsule(capsuleId) {
+  // Stub implementation
+  return {
+    success: true,
+    outputHash: 'stub-hash',
+    verified: true,
+  };
+}
+
+/**
+ * Replay multiple capsules
+ * @param {string[]} capsuleIds - Capsule IDs
+ * @returns {Promise<{total: number, verified: number, failed: number}>}
+ */
+export async function replayBatch(capsuleIds) {
+  const results = await Promise.all(
+    capsuleIds.map(id => replayCapsule(id))
+  );
+
+  const verified = results.filter(r => r.verified).length;
+
+  return {
+    total: capsuleIds.length,
+    verified,
+    failed: capsuleIds.length - verified,
+  };
+}

package/src/tool-wrapper.mjs

@@ -0,0 +1,156 @@
+/**
+ * @file Tool Wrapper - Contract Enforcement Layer
+ * @module @unrdf/kgc-tools/tool-wrapper
+ * @description Wraps tools to enforce input/output contracts and generate execution receipts
+ */
+
+import { z } from 'zod';
+
+/**
+ * Receipt schema for tool execution
+ */
+const ReceiptSchema = z.object({
+  tool_name: z.string(),
+  version: z.string(),
+  inputs: z.any(),
+  outputs: z.any().nullable(),
+  status: z.enum(['success', 'error']),
+  timestamp: z.number(),
+  execution_time_ms: z.number(),
+  error: z.string().optional(),
+});
+
+/**
+ * Wraps a tool function to enforce contracts and generate receipts
+ *
+ * @param {Function} tool - The tool function to wrap
+ * @param {Object} manifest - Tool manifest with schema and metadata
+ * @param {string} manifest.name - Tool name
+ * @param {string} manifest.version - Tool version
+ * @param {z.ZodSchema} manifest.schema_in - Input validation schema
+ * @param {z.ZodSchema} manifest.schema_out - Output validation schema
+ * @param {string[]} manifest.capabilities - Tool capabilities
+ * @returns {Function} Wrapped tool function
+ *
+ * @example
+ * const readTool = async (inputs) => ({
+ *   content: 'file content',
+ *   size: 100
+ * });
+ *
+ * const manifest = {
+ *   name: 'Read',
+ *   version: '1.0.0',
+ *   schema_in: z.object({ path: z.string() }),
+ *   schema_out: z.object({ content: z.string(), size: z.number() }),
+ *   capabilities: ['file-read']
+ * };
+ *
+ * const wrapped = Wrap(readTool, manifest);
+ * const result = await wrapped({ path: '/test.txt' });
+ * // Returns: { delta: {...}, receipt: {...} }
+ */
+export function Wrap(tool, manifest) {
+  // Validate manifest structure (basic validation)
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error('Manifest must be an object');
+  }
+  if (!manifest.name || typeof manifest.name !== 'string') {
+    throw new Error('Manifest must have a name string');
+  }
+  if (!manifest.version || typeof manifest.version !== 'string') {
+    throw new Error('Manifest must have a version string');
+  }
+  if (!manifest.schema_in || typeof manifest.schema_in.parse !== 'function') {
+    throw new Error('Manifest must have a schema_in with parse method');
+  }
+  if (!manifest.schema_out || typeof manifest.schema_out.parse !== 'function') {
+    throw new Error('Manifest must have a schema_out with parse method');
+  }
+  if (!Array.isArray(manifest.capabilities)) {
+    throw new Error('Manifest must have capabilities array');
+  }
+
+  /**
+   * Wrapped tool function
+   * @param {*} inputs - Tool inputs to validate
+   * @returns {Promise<{delta: *, receipt: Object}>} Execution result with delta and receipt
+   */
+  return async function wrappedTool(inputs) {
+    const startTime = performance.now();
+    const timestamp = Date.now();
+
+    let validatedInputs;
+    let outputs = null;
+    let delta = null;
+    let status = 'success';
+    let errorMessage;
+
+    try {
+      // Validate inputs against schema_in
+      validatedInputs = manifest.schema_in.parse(inputs);
+
+      // Execute the tool
+      const rawOutputs = await tool(validatedInputs);
+
+      // Validate outputs against schema_out
+      outputs = manifest.schema_out.parse(rawOutputs);
+
+      // Delta is the validated output
+      delta = outputs;
+      status = 'success';
+    } catch (error) {
+      // Handle validation or execution errors
+      status = 'error';
+      errorMessage = error.message;
+      outputs = null;
+      delta = null;
+
+      // Re-validate inputs if they weren't validated yet
+      if (!validatedInputs) {
+        validatedInputs = inputs;
+      }
+    }
+
+    const endTime = performance.now();
+    const executionTimeMs = endTime - startTime;
+
+    // Build receipt
+    const receipt = {
+      tool_name: manifest.name,
+      version: manifest.version,
+      inputs: validatedInputs,
+      outputs,
+      status,
+      timestamp,
+      execution_time_ms: executionTimeMs,
+    };
+
+    // Add error field if present
+    if (errorMessage) {
+      receipt.error = errorMessage;
+    }
+
+    // Validate receipt structure
+    ReceiptSchema.parse(receipt);
+
+    return {
+      delta,
+      receipt,
+    };
+  };
+}
+
+/**
+ * Validates a receipt structure
+ * @param {*} receipt - Receipt to validate
+ * @returns {boolean} True if valid
+ */
+export function validateReceipt(receipt) {
+  try {
+    ReceiptSchema.parse(receipt);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/verify.mjs

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Verification tools for KGC capsules, freezes, and receipts
+ */
+
+import { verifyReceiptHash, verifyReceiptChain } from '@unrdf/kgc-runtime';
+import { verifyReceipt as kgc4dVerifyReceipt } from '@unrdf/kgc-4d';
+
+/**
+ * Verify all receipts in a directory
+ * @param {string} receiptPath - Path to receipts
+ * @returns {Promise<{valid: boolean, verified: number, errors: string[]}>}
+ */
+export async function verifyAllReceipts(receiptPath = '.kgc/receipts') {
+  // Stub implementation - would read from filesystem
+  return {
+    valid: true,
+    verified: 0,
+    errors: [],
+  };
+}
+
+/**
+ * Verify a freeze snapshot
+ * @param {string} freezeId - Freeze snapshot ID
+ * @returns {Promise<{valid: boolean, capsules: number, errors: string[]}>}
+ */
+export async function verifyFreeze(freezeId) {
+  // Stub implementation
+  return {
+    valid: true,
+    capsules: 0,
+    errors: [],
+  };
+}
+
+/**
+ * Verify documentation matches code
+ * @param {string} docsPath - Documentation path
+ * @returns {Promise<{valid: boolean, verified: number, errors: string[]}>}
+ */
+export async function verifyDocs(docsPath = 'docs') {
+  // Stub implementation
+  return {
+    valid: true,
+    verified: 0,
+    errors: [],
+  };
+}
+
+/**
+ * Comprehensive verification of all KGC components
+ * @returns {Promise<{receipts: any, freezes: any, docs: any, overall: boolean}>}
+ */
+export async function verifyAll() {
+  const receipts = await verifyAllReceipts();
+  const docs = await verifyDocs();
+
+  return {
+    receipts,
+    freezes: { valid: true, capsules: 0, errors: [] },
+    docs,
+    overall: receipts.valid && docs.valid,
+  };
+}