@unrdf/kgc-runtime 26.4.2

package/docs/api-stability.md

@@ -0,0 +1,269 @@
+# KGC Runtime API Stability and Deprecation Policy
+
+## Current Version
+
+**API Version**: 5.0.1 (Beta)
+
+**Status**: Beta - API is stable but may have minor changes before 5.1.0 stable release
+
+## Semantic Versioning
+
+KGC Runtime follows [Semantic Versioning 2.0.0](https://semver.org/):
+
+```
+MAJOR.MINOR.PATCH
+
+5.0.1
+│ │ └─ Patch: Backward compatible bug fixes
+│ └─── Minor: Backward compatible new features
+└───── Major: Breaking changes
+```
+
+### Version Guarantees
+
+- **Patch (x.x.PATCH)**: Bug fixes, no API changes
+- **Minor (x.MINOR.x)**: New features, fully backward compatible
+- **Major (MAJOR.x.x)**: Breaking changes, may require migration
+
+## Deprecation Policy
+
+### Overview
+
+To ensure smooth transitions and maintain stability, we follow a strict deprecation policy:
+
+**Rule**: APIs are deprecated for **minimum 2 releases** before removal
+
+**Minimum Deprecation Period**: 90 days
+
+### Deprecation Process
+
+#### 1. Announcement (Release N)
+
+API feature is marked as deprecated:
+
+```javascript
+/**
+ * @deprecated Since v5.0.0. Use newFunction() instead.
+ * Will be removed in v7.0.0 (March 2025)
+ */
+export function oldFunction() {
+  console.warn('[DEPRECATION] oldFunction is deprecated. Use newFunction instead.');
+  // ... implementation continues to work
+}
+```
+
+#### 2. Warning Period (Releases N+1, N+2)
+
+Deprecated APIs continue to function but emit warnings:
+
+```
+[DEPRECATION WARNING] oldFunction is deprecated since v5.0.0.
+Use newFunction instead. Removal scheduled for v7.0.0 (March 2025).
+```
+
+#### 3. Removal (Release N+3 or later)
+
+After minimum 90 days AND 2 releases, API is removed:
+
+```javascript
+// v7.0.0 - Function removed
+// Import will fail
+// Migration guide: docs/migration/v5-to-v7.md
+```
+
+## API Stability Levels
+
+### Stable
+
+- **Guarantee**: No breaking changes in minor/patch versions
+- **Deprecation**: Minimum 2 releases + 90 days notice
+- **Examples**: Core schemas, receipt generation, work items
+
+```javascript
+// Stable API - Won't change in 5.x.x
+import { ReceiptSchema } from '@unrdf/kgc-runtime/schemas';
+```
+
+### Beta
+
+- **Guarantee**: API shape is stable but may have additions
+- **Changes**: New fields/methods can be added in minor versions
+- **Deprecation**: Same as stable (2 releases + 90 days)
+- **Examples**: Plugin system (v5.0.1), API versioning
+
+```javascript
+// Beta API - Stable but may expand
+import { PluginManager } from '@unrdf/kgc-runtime/plugin-manager';
+```
+
+### Experimental
+
+- **Guarantee**: None - can change or be removed at any time
+- **Usage**: Not recommended for production
+- **Warning**: Clearly marked in documentation
+
+```javascript
+// Experimental API - Use at your own risk
+// @experimental
+import { ExperimentalFeature } from '@unrdf/kgc-runtime/experimental';
+```
+
+## Version Compatibility
+
+### Plugin API Version Checking
+
+Plugins must declare their required API version:
+
+```json
+{
+  "name": "my-plugin",
+  "api_version": "5.0.1"
+}
+```
+
+Runtime validates compatibility:
+
+```javascript
+import { validatePluginVersion } from '@unrdf/kgc-runtime/api-version';
+
+try {
+  validatePluginVersion('5.0.0'); // OK - compatible
+  validatePluginVersion('4.0.0'); // WARNING - deprecated
+  validatePluginVersion('3.0.0'); // ERROR - removed
+} catch (error) {
+  console.error('Incompatible plugin version:', error.message);
+}
+```
+
+### Compatibility Rules
+
+| Plugin API | Runtime 5.0.1 | Status |
+|-----------|---------------|---------|
+| 5.0.1 | ✅ Compatible | Exact match |
+| 5.0.0 | ✅ Compatible | Patch difference OK |
+| 4.9.9 | ⚠️ Deprecated | Works but warns |
+| 3.x.x | ❌ Removed | Error thrown |
+
+## Migration Guides
+
+When breaking changes occur, we provide comprehensive migration guides:
+
+### Example: v4 to v5 Migration
+
+**Location**: `docs/migration/v4-to-v5.md`
+
+**Contents**:
+1. Breaking changes summary
+2. Step-by-step migration instructions
+3. Code examples (before/after)
+4. Automated migration scripts
+5. Testing recommendations
+
+```javascript
+// v4 (deprecated)
+const receipt = generateReceipt(op, data);
+
+// v5 (current)
+const receipt = await generateReceipt(op, inputs, outputs, parentHash);
+```
+
+## Deprecation Timeline
+
+### Current Deprecations (v5.0.1)
+
+| Feature | Deprecated | Removal | Alternative |
+|---------|-----------|---------|-------------|
+| `WorkItem.metadata` direct mutation | v5.0.0 | v7.0.0 | Use `updateMetadata()` method |
+| `Receipt.hash` MD5 | v4.0.0 | v6.0.0 | Now using BLAKE3 (automatic) |
+
+### Upcoming Changes (Planned)
+
+| Feature | Target Version | Type | Description |
+|---------|---------------|------|-------------|
+| Plugin hot-reload | v5.1.0 | Addition | Reload plugins without restart |
+| WASM plugin support | v5.2.0 | Addition | Run plugins in WASM sandbox |
+| GraphQL API | v6.0.0 | Addition | Query runtime via GraphQL |
+
+## Stability Guarantees by Module
+
+### Core Runtime (Stable)
+
+- ✅ `schemas.mjs` - All core schemas
+- ✅ `receipt.mjs` - Receipt generation/validation
+- ✅ `work-item.mjs` - Work item executor
+- ✅ `bounds.mjs` - Bounds checking
+- ✅ `capsule.mjs` - Run capsule management
+
+### Plugin System (Beta)
+
+- 🔶 `plugin-manager.mjs` - Plugin lifecycle
+- 🔶 `plugin-isolation.mjs` - Capability security
+- 🔶 `api-version.mjs` - Version management
+
+### Governance (Beta)
+
+- 🔶 `admission-gate.mjs` - Policy enforcement
+- 🔶 `freeze-restore.mjs` - State snapshots
+- 🔶 `merge.mjs` - State merging
+
+## Breaking Change Policy
+
+### What Constitutes a Breaking Change?
+
+**Breaking** (requires major version):
+- Removing exported function/class
+- Changing function signature (params, return type)
+- Changing schema validation rules (stricter)
+- Removing schema fields
+- Changing default behavior
+
+**Not Breaking** (minor/patch version):
+- Adding new function/class
+- Adding optional parameters
+- Adding schema fields (optional)
+- Relaxing validation rules
+- Internal implementation changes
+- Performance improvements
+
+### Example Scenarios
+
+```javascript
+// ❌ BREAKING - Requires v6.0.0
+// v5: generateReceipt(op, data)
+// v6: generateReceipt(op, inputs, outputs) // Changed signature
+
+// ✅ NOT BREAKING - Can be v5.1.0
+// v5.0: generateReceipt(op, inputs, outputs)
+// v5.1: generateReceipt(op, inputs, outputs, options = {}) // Added optional param
+```
+
+## Staying Updated
+
+### Subscribe to Changes
+
+1. **GitHub Releases**: Watch the repository
+2. **Changelog**: Check `CHANGELOG.md` for each release
+3. **Migration Alerts**: Run `npm outdated` for deprecation warnings
+
+### Automated Checks
+
+Add to your CI/CD:
+
+```bash
+# Check for deprecated API usage
+npm run check-deprecations
+
+# Validate plugin compatibility
+npm run validate-plugin-version
+```
+
+## Questions?
+
+- **Deprecation Questions**: Open an issue with tag `deprecation`
+- **Migration Help**: Check `docs/migration/` or ask in Discussions
+- **Breaking Change Proposals**: RFC process in GitHub Discussions
+
+---
+
+**Last Updated**: 2024-12-27
+**Next Review**: 2025-03-01 (with v5.1.0 release)

package/docs/extensions/plugin-development.md

@@ -0,0 +1,382 @@
+# KGC Plugin Development Guide
+
+## Overview
+
+The KGC Runtime plugin system allows you to extend core functionality with custom receipt types, validators, and tools while maintaining security and deterministic execution.
+
+## Quick Start
+
+### 1. Create Plugin Manifest
+
+```javascript
+// plugin.json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "My custom KGC plugin",
+  "entryPoint": "./index.mjs",
+  "capabilities": [
+    "receipt:generate",
+    "receipt:validate"
+  ],
+  "api_version": "5.0.1",
+  "author": "Your Name",
+  "license": "MIT"
+}
+```
+
+### 2. Implement Plugin
+
+```javascript
+// index.mjs
+import { PluginReceiptSchema } from '@unrdf/kgc-runtime/schemas';
+
+/**
+ * Plugin entry point
+ * @param {Object} runtime - KGC Runtime API (whitelisted methods only)
+ */
+export default function plugin(runtime) {
+  return {
+    name: 'my-plugin',
+    version: '1.0.0',
+
+    /**
+     * Initialize plugin
+     */
+    async initialize() {
+      console.log('Plugin initialized');
+    },
+
+    /**
+     * Generate custom receipt
+     */
+    async generateCustomReceipt(operation, inputs, outputs) {
+      const receipt = await runtime.generateReceipt(operation, inputs, outputs);
+
+      // Add custom metadata
+      return PluginReceiptSchema.parse({
+        ...receipt,
+        pluginMetadata: {
+          pluginName: 'my-plugin',
+          pluginVersion: '1.0.0',
+          receiptType: 'custom',
+          customFields: {
+            myData: 'example'
+          }
+        }
+      });
+    },
+
+    /**
+     * Cleanup on unload
+     */
+    async cleanup() {
+      console.log('Plugin cleanup');
+    }
+  };
+}
+```
+
+### 3. Register and Use
+
+```javascript
+import { PluginManager } from '@unrdf/kgc-runtime/plugin-manager';
+
+const manager = new PluginManager();
+
+// Register plugin
+await manager.registerPlugin({
+  name: 'my-plugin',
+  version: '1.0.0',
+  entryPoint: './plugin.mjs',
+  capabilities: ['receipt:generate'],
+  api_version: '5.0.1'
+});
+
+// Load and activate
+await manager.loadPlugin('my-plugin@1.0.0');
+await manager.activatePlugin('my-plugin@1.0.0');
+```
+
+## API Reference
+
+### Available Runtime APIs (Whitelisted)
+
+Plugins can only access these whitelisted APIs:
+
+```javascript
+runtime = {
+  // Receipt operations
+  generateReceipt(operation, inputs, outputs, parentHash),
+  verifyReceiptHash(receipt),
+
+  // Schema validation
+  validateReceipt(receipt),
+  validateWorkItem(workItem),
+  validateBounds(bounds),
+
+  // Tool registry (read-only)
+  getTool(name),
+  getToolsByCapability(capability),
+
+  // Bounds checking
+  checkBounds(current, limits)
+}
+```
+
+### Blocked Capabilities
+
+The following are NEVER allowed for security:
+
+- `filesystem:write` - Direct file writes
+- `filesystem:delete` - File deletion
+- `network:http` - HTTP requests
+- `network:socket` - Socket connections
+- `process:spawn` - Process spawning
+- `process:exit` - Process termination
+- `eval:code` - Dynamic code evaluation
+
+## Plugin Lifecycle
+
+```
+REGISTERED → LOADED → EXECUTING → UNLOADED
+     ↓                    ↓
+  FAILED ←──────────────────
+```
+
+### State Transitions
+
+1. **REGISTERED**: Plugin manifest validated and registered
+2. **LOADED**: Plugin code loaded into memory, `initialize()` called
+3. **EXECUTING**: Plugin actively processing requests
+4. **UNLOADED**: Plugin stopped, `cleanup()` called
+5. **FAILED**: Error occurred, check audit log
+
+## Custom Receipt Types
+
+Define custom receipt schemas:
+
+```javascript
+import { z } from 'zod';
+import { PluginReceiptSchema } from '@unrdf/kgc-runtime/schemas';
+
+// Define custom receipt type
+const MyCustomReceiptSchema = PluginReceiptSchema.extend({
+  pluginMetadata: z.object({
+    pluginName: z.literal('my-plugin'),
+    pluginVersion: z.string(),
+    receiptType: z.literal('performance'),
+    customFields: z.object({
+      executionTime: z.number(),
+      memoryUsed: z.number(),
+      optimizationApplied: z.boolean()
+    })
+  })
+});
+
+// Generate typed receipt
+export async function generatePerformanceReceipt(operation, metrics) {
+  const receipt = await runtime.generateReceipt(operation, {}, metrics);
+
+  return MyCustomReceiptSchema.parse({
+    ...receipt,
+    pluginMetadata: {
+      pluginName: 'my-plugin',
+      pluginVersion: '1.0.0',
+      receiptType: 'performance',
+      customFields: {
+        executionTime: metrics.duration,
+        memoryUsed: metrics.memory,
+        optimizationApplied: metrics.optimized
+      }
+    }
+  });
+}
+```
+
+## Security Best Practices
+
+### 1. Capability Declaration
+
+Always declare minimum required capabilities:
+
+```javascript
+{
+  "capabilities": [
+    "receipt:generate",    // Only what you need
+    "receipt:validate"
+  ]
+}
+```
+
+### 2. Input Validation
+
+Validate all inputs with Zod schemas:
+
+```javascript
+import { z } from 'zod';
+
+const InputSchema = z.object({
+  operation: z.string().min(1).max(100),
+  data: z.record(z.any())
+});
+
+export async function processInput(input) {
+  // Validate first
+  const validated = InputSchema.parse(input);
+
+  // Then process
+  return validated;
+}
+```
+
+### 3. Error Handling
+
+Use proper error receipts:
+
+```javascript
+try {
+  const result = await riskyOperation();
+  return await runtime.generateReceipt('success', {}, { result });
+} catch (error) {
+  return await runtime.generateReceipt('error', {}, {
+    success: false,
+    error: error.message,
+    stack: error.stack
+  });
+}
+```
+
+## Testing Plugins
+
+### Unit Tests
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import myPlugin from './plugin.mjs';
+
+describe('My Plugin', () => {
+  it('should initialize correctly', async () => {
+    const mockRuntime = {
+      generateReceipt: async (op, inp, out) => ({
+        id: 'test',
+        operation: op
+      })
+    };
+
+    const plugin = myPlugin(mockRuntime);
+    await plugin.initialize();
+
+    expect(plugin.name).toBe('my-plugin');
+  });
+
+  it('should generate custom receipts', async () => {
+    const mockRuntime = {
+      generateReceipt: async (op, inp, out) => ({
+        id: 'test',
+        timestamp: Date.now(),
+        operation: op,
+        inputs: inp,
+        outputs: out,
+        hash: 'abc123'
+      })
+    };
+
+    const plugin = myPlugin(mockRuntime);
+    const receipt = await plugin.generateCustomReceipt('test', {}, {});
+
+    expect(receipt.pluginMetadata).toBeDefined();
+    expect(receipt.pluginMetadata.pluginName).toBe('my-plugin');
+  });
+});
+```
+
+### Integration Tests
+
+```javascript
+import { PluginManager } from '@unrdf/kgc-runtime/plugin-manager';
+import { PluginIsolation } from '@unrdf/kgc-runtime/plugin-isolation';
+
+describe('Plugin Integration', () => {
+  it('should load and execute with isolation', async () => {
+    const manager = new PluginManager();
+    const isolation = new PluginIsolation({
+      whitelist: ['receipt:generate']
+    });
+
+    await manager.registerPlugin({
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test-plugin.mjs',
+      capabilities: ['receipt:generate'],
+      api_version: '5.0.1'
+    });
+
+    await manager.loadPlugin('test-plugin@1.0.0');
+
+    const state = manager.getPluginState('test-plugin@1.0.0');
+    expect(state).toBe('loaded');
+  });
+});
+```
+
+## Publishing Plugins
+
+### 1. Prepare Package
+
+```json
+{
+  "name": "@my-scope/kgc-plugin-name",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "peerDependencies": {
+    "@unrdf/kgc-runtime": "^1.0.0"
+  }
+}
+```
+
+### 2. Test Thoroughly
+
+```bash
+# Run all tests
+npm test
+
+# Check type safety
+npm run typecheck
+
+# Verify capabilities
+npm run verify-plugin
+```
+
+### 3. Submit to Registry
+
+Create a PR to the [KGC Plugin Registry](https://github.com/unrdf/kgc-plugins):
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "My custom plugin",
+  "repository": "https://github.com/my-org/my-plugin",
+  "verified": false
+}
+```
+
+## Examples
+
+See `templates/plugin-template/` for a complete example plugin with:
+- Manifest configuration
+- Receipt generation
+- Input validation
+- Error handling
+- Comprehensive tests
+
+## Support
+
+- Documentation: https://unrdf.github.io/kgc-runtime
+- Issues: https://github.com/unrdf/kgc-runtime/issues
+- Discussions: https://github.com/unrdf/kgc-runtime/discussions

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@unrdf/kgc-runtime",
+  "version": "26.4.2",
+  "description": "KGC governance runtime with comprehensive Zod schemas and work item system",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./schemas": "./src/schemas.mjs",
+    "./work-item": "./src/work-item.mjs",
+    "./plugin-manager": "./src/plugin-manager.mjs",
+    "./plugin-isolation": "./src/plugin-isolation.mjs",
+    "./api-version": "./src/api-version.mjs"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "kgc",
+    "governance",
+    "runtime",
+    "schemas",
+    "zod",
+    "validation",
+    "work-item",
+    "async"
+  ],
+  "author": "UNRDF Team",
+  "license": "MIT",
+  "dependencies": {
+    "@unrdf/oxigraph": "workspace:*",
+    "hash-wasm": "^4.11.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.15"
+  }
+}